From 99d420a5e4917d3bad10850a6251633f374d0a30 Mon Sep 17 00:00:00 2001 From: Michael Date: Tue, 1 Oct 2024 10:50:30 +0800 Subject: [PATCH] Tweak and clean up pr-wranglers and linkchecke readme --- .../contribute/participate/pr-wranglers.md | 55 ++++++++++--------- .../linkchecker/README.md | 45 ++++++++++----- 2 files changed, 58 insertions(+), 42 deletions(-) diff --git a/content/en/docs/contribute/participate/pr-wranglers.md b/content/en/docs/contribute/participate/pr-wranglers.md index cf5162d68dda2..44ce4ead3db61 100644 --- a/content/en/docs/contribute/participate/pr-wranglers.md +++ b/content/en/docs/contribute/participate/pr-wranglers.md @@ -22,40 +22,42 @@ Each day in a week-long shift as PR Wrangler: - Review [open pull requests](https://github.com/kubernetes/website/pulls) for quality and adherence to the [Style](/docs/contribute/style/style-guide/) and [Content](/docs/contribute/style/content-guide/) guides. - - Start with the smallest PRs (`size/XS`) first, and end with the largest (`size/XXL`). Review as many PRs as you can. + - Start with the smallest PRs (`size/XS`) first, and end with the largest (`size/XXL`). + Review as many PRs as you can. - Make sure PR contributors sign the [CLA](https://github.com/kubernetes/community/blob/master/CLA.md). - - Use [this](https://github.com/zparnold/k8s-docs-pr-botherer) script to remind contributors - that haven't signed the CLA to do so. + - Use [this](https://github.com/zparnold/k8s-docs-pr-botherer) script to remind contributors + that haven't signed the CLA to do so. - Provide feedback on changes and ask for technical reviews from members of other SIGs. - - Provide inline suggestions on the PR for the proposed content changes. - - If you need to verify content, comment on the PR and request more details. - - Assign relevant `sig/` label(s). - - If needed, assign reviewers from the `reviewers:` block in the file's front matter. - - You can also tag a [SIG](https://github.com/kubernetes/community/blob/master/sig-list.md) - for a review by commenting `@kubernetes/-pr-reviews` on the PR. + - Provide inline suggestions on the PR for the proposed content changes. + - If you need to verify content, comment on the PR and request more details. + - Assign relevant `sig/` label(s). + - If needed, assign reviewers from the `reviewers:` block in the file's front matter. + - You can also tag a [SIG](https://github.com/kubernetes/community/blob/master/sig-list.md) + for a review by commenting `@kubernetes/-pr-reviews` on the PR. - Use the `/approve` comment to approve a PR for merging. Merge the PR when ready. - - PRs should have a `/lgtm` comment from another member before merging. - - Consider accepting technically accurate content that doesn't meet the - [style guidelines](/docs/contribute/style/style-guide/). As you approve the change, - open a new issue to address the style concern. You can usually write these style fix - issues as [good first issues](https://kubernetes.dev/docs/guide/help-wanted/#good-first-issue). - - Using style fixups as good first issues is a good way to ensure a supply of easier tasks - to help onboard new contributors. -- Also check for pull requests against the [reference docs generator](https://github.com/kubernetes-sigs/reference-docs) code, and review those (or bring in help). + - PRs should have a `/lgtm` comment from another member before merging. + - Consider accepting technically accurate content that doesn't meet the + [style guidelines](/docs/contribute/style/style-guide/). As you approve the change, + open a new issue to address the style concern. You can usually write these style fix + issues as [good first issues](https://kubernetes.dev/docs/guide/help-wanted/#good-first-issue). + - Using style fixups as good first issues is a good way to ensure a supply of easier tasks + to help onboard new contributors. +- Also check for pull requests against the [reference docs generator](https://github.com/kubernetes-sigs/reference-docs) + code, and review those (or bring in help). - Support the [issue wrangler](/docs/contribute/participate/issue-wrangler/) to triage and tag incoming issues daily. See [Triage and categorize issues](/docs/contribute/review/for-approvers/#triage-and-categorize-issues) for guidelines on how SIG Docs uses metadata. {{< note >}} -PR wrangler duties do not apply to localization PRs (non-English PRs). -Localization teams have their own processes and teams for reviewing their language PRs. -However, it's often helpful to ensure language PRs are labeled correctly, -review small non-language dependent PRs (like a link update), -or tag reviewers or contributors in long-running PRs (ones opened more than 6 months ago and have not been updated in a month or more). +PR wrangler duties do not apply to localization PRs (non-English PRs). +Localization teams have their own processes and teams for reviewing their language PRs. +However, it's often helpful to ensure language PRs are labeled correctly, +review small non-language dependent PRs (like a link update), +or tag reviewers or contributors in long-running PRs +(ones opened more than 6 months ago and have not been updated in a month or more). {{< /note >}} - ### Helpful GitHub queries for wranglers The following queries are helpful when wrangling. @@ -99,10 +101,11 @@ These queries exclude localization PRs. All queries are against the main branch Reviews and approvals are one tool to keep our PR queue short and current. Another tool is closure. Close PRs where: + - The author hasn't signed the CLA for two weeks. - Authors can reopen the PR after signing the CLA. This is a low-risk way to make - sure nothing gets merged without a signed CLA. + Authors can reopen the PR after signing the CLA. This is a low-risk way to make + sure nothing gets merged without a signed CLA. - The author has not responded to comments or feedback in 2 or more weeks. @@ -112,11 +115,9 @@ Often a closure notice is what spurs an author to resume and finish their contri To close a pull request, leave a `/close` comment on the PR. {{< note >}} - The [`k8s-triage-robot`](https://github.com/k8s-triage-robot) bot marks issues as stale after 90 days of inactivity. After 30 more days it marks issues as rotten and closes them. PR wranglers should close issues after 14-30 days of inactivity. - {{< /note >}} ## PR Wrangler shadow program diff --git a/content/en/docs/doc-contributor-tools/linkchecker/README.md b/content/en/docs/doc-contributor-tools/linkchecker/README.md index 6d4b714655e42..264472ac34106 100644 --- a/content/en/docs/doc-contributor-tools/linkchecker/README.md +++ b/content/en/docs/doc-contributor-tools/linkchecker/README.md @@ -1,39 +1,52 @@ # Internal link checking tool -You can use [htmltest](https://github.com/wjdp/htmltest) to check for broken links in [`/content/en/`](https://git.k8s.io/website/content/en/). This is useful when refactoring sections of content, moving pages around, or renaming files or page headers. +You can use [htmltest](https://github.com/wjdp/htmltest) to check for broken links in +[`/content/en/`](https://git.k8s.io/website/content/en/). This is useful when refactoring +sections of content, moving pages around, or renaming files or page headers. ## How the tool works -`htmltest` scans links in the generated HTML files of the kubernetes website repository. It runs using a `make` command which does the following: +`htmltest` scans links in the generated HTML files of the kubernetes website repository. +It runs using a `make` command which does the following: -- Builds the site and generates output HTML in the `/public` directory of your local `kubernetes/website` repository +- Builds the site and generates output HTML in the `/public` directory of your + local `kubernetes/website` repository - Pulls the `wdjp/htmltest` Docker image - Mounts your local `kubernetes/website` repository to the Docker image -- Scans the files generated in the `/public` directory and provides command line output when it encounters broken internal links +- Scans the files generated in the `/public` directory and provides command line + output when it encounters broken internal links ## What it does and doesn't check -The link checker scans generated HTML files, not raw Markdown. The htmltest tool depends on a configuration file, [`.htmltest.yml`](https://git.k8s.io/website/.htmltest.yml), to determine which content to examine. +The link checker scans generated HTML files, not raw Markdown. +The htmltest tool depends on a configuration file, +[`.htmltest.yml`](https://git.k8s.io/website/.htmltest.yml), +to determine which content to examine. The link checker scans the following: -- All content generated from Markdown in [`/content/en/docs`](https://git.k8s.io/website/content/en/docs/) directory, excluding: - - Generated API references, for example https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ +- All content generated from Markdown in + [`/content/en/docs`](https://git.k8s.io/website/content/en/docs/) directory, excluding: + - Generated API references, for example + https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ - All internal links, excluding: - Empty hashes (`` or `[title](#)`) and empty hrefs (`` or `[title]()`) - Internal links to images and other media files The link checker does not scan the following: -- Links included in the top and side nav bars, footer links, or links in a page's `` section, such as links to CSS stylesheets, scripts, and meta information +- Links included in the top and side nav bars, footer links, or links in a page's `` section, + such as links to CSS stylesheets, scripts, and meta information - Top level pages and their children, for example: `/training`, `/community`, `/case-studies/adidas` - Blog posts -- API Reference documentation, for example: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ +- API Reference documentation, for example + https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ - Localizations ## Prerequisites and installation You must install + * [Docker](https://docs.docker.com/get-docker/) * [make](https://www.gnu.org/software/make/) @@ -45,9 +58,9 @@ To run the link checker: 2. Run the following command: - ``` - make container-internal-linkcheck - ``` + ```shell + make container-internal-linkcheck + ``` ## Understanding the output @@ -70,7 +83,9 @@ The target URL is `#preserving-unknown-fields`. One way to fix this is to: 1. Navigate to the Markdown file with a broken link. -2. Using a text editor, do a full-text search (usually Ctrl+F or Command+F) for the broken link's URL, `#preserving-unknown-fields`. -3. Fix the link. For a broken page hash (or _anchor_) link, check whether the topic was renamed or removed. +1. Using a text editor, do a full-text search (usually Ctrl+F or Command+F) for the + broken link's URL, `#preserving-unknown-fields`. +1. Fix the link. For a broken page hash (or _anchor_) link, + check whether the topic was renamed or removed. -Run htmltest to verify that broken links are fixed. \ No newline at end of file +Run htmltest to verify that broken links are fixed.