|
| 1 | +--- |
| 2 | +title: Reviewing pull requests |
| 3 | +content_type: concept |
| 4 | +main_menu: true |
| 5 | +weight: 10 |
| 6 | +--- |
| 7 | + |
| 8 | +<!-- overview --> |
| 9 | + |
| 10 | +Anyone can review a documentation pull request. Visit the [pull requests](https://github.com/kubernetes/website/pulls) section in the Kubernetes website repository to see open pull requests. |
| 11 | + |
| 12 | +Reviewing documentation pull requests is a |
| 13 | +great way to introduce yourself to the Kubernetes community. |
| 14 | +It helps you learn the code base and build trust with other contributors. |
| 15 | + |
| 16 | +Before reviewing, it's a good idea to: |
| 17 | + |
| 18 | +- Read the [content guide](/docs/contribute/style/content-guide/) and |
| 19 | + [style guide](/docs/contribute/style/style-guide/) so you can leave informed comments. |
| 20 | +- Understand the different |
| 21 | + [roles and responsibilities](/docs/contribute/participate/roles-and-responsibilities/) |
| 22 | + in the Kubernetes documentation community. |
| 23 | + |
| 24 | +<!-- body --> |
| 25 | + |
| 26 | +## Before you begin |
| 27 | + |
| 28 | +Before you start a review: |
| 29 | + |
| 30 | +- Read the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and ensure that you abide by it at all times. |
| 31 | +- Be polite, considerate, and helpful. |
| 32 | +- Comment on positive aspects of PRs as well as changes. |
| 33 | +- Be empathetic and mindful of how your review may be received. |
| 34 | +- Assume good intent and ask clarifying questions. |
| 35 | +- Experienced contributors, consider pairing with new contributors whose work requires extensive changes. |
| 36 | + |
| 37 | +## Review process |
| 38 | + |
| 39 | +In general, review pull requests for content and style in English. |
| 40 | + |
| 41 | +1. Go to |
| 42 | + [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls). |
| 43 | + You see a list of every open pull request against the Kubernetes website and |
| 44 | + docs. |
| 45 | + |
| 46 | +2. Filter the open PRs using one or all of the following labels: |
| 47 | + - `cncf-cla: yes` (Recommended): PRs submitted by contributors who have not signed the CLA cannot be merged. See [Sign the CLA](/docs/contribute/new-content/overview/#sign-the-cla) for more information. |
| 48 | + - `language/en` (Recommended): Filters for english language PRs only. |
| 49 | + - `size/<size>`: filters for PRs of a certain size. If you're new, start with smaller PRs. |
| 50 | + |
| 51 | + Additionally, ensure the PR isn't marked as a work in progress. PRs using the `work in progress` label are not ready for review yet. |
| 52 | + |
| 53 | +3. Once you've selected a PR to review, understand the change by: |
| 54 | + - Reading the PR description to understand the changes made, and read any linked issues |
| 55 | + - Reading any comments by other reviewers |
| 56 | + - Clicking the **Files changed** tab to see the files and lines changed |
| 57 | + - Previewing the changes in the Netlify preview build by scrolling to the PR's build check section at the bottom of the **Conversation** tab and clicking the **deploy/netlify** line's **Details** link. |
| 58 | + |
| 59 | +4. Go to the **Files changed** tab to start your review. |
| 60 | + 1. Click on the `+` symbol beside the line you want to comment on. |
| 61 | + 2. Fill in any comments you have about the line and click either **Add single comment** (if you have only one comment to make) or **Start a review** (if you have multiple comments to make). |
| 62 | + 3. When finished, click **Review changes** at the top of the page. Here, you can add |
| 63 | + add a summary of your review (and leave some positive comments for the contributor!), |
| 64 | + approve the PR, comment or request changes as needed. New contributors should always |
| 65 | + choose **Comment**. |
| 66 | + |
| 67 | +## Reviewing checklist |
| 68 | + |
| 69 | +When reviewing, use the following as a starting point. |
| 70 | + |
| 71 | +### Language and grammar |
| 72 | + |
| 73 | +- Are there any obvious errors in language or grammar? Is there a better way to phrase something? |
| 74 | +- Are there any complicated or archaic words which could be replaced with a simpler word? |
| 75 | +- Are there any words, terms or phrases in use which could be replaced with a non-discriminatory alternative? |
| 76 | +- Does the word choice and its capitalization follow the [style guide](/docs/contribute/style/style-guide/)? |
| 77 | +- Are there long sentences which could be shorter or less complex? |
| 78 | +- Are there any long paragraphs which might work better as a list or table? |
| 79 | + |
| 80 | +### Content |
| 81 | + |
| 82 | +- Does similar content exist elsewhere on the Kubernetes site? |
| 83 | +- Does the content excessively link to off-site, individual vendor or non-open source documentation? |
| 84 | + |
| 85 | +### Website |
| 86 | + |
| 87 | +- Did this PR change or remove a page title, slug/alias or anchor link? If so, are there broken links as a result of this PR? Is there another option, like changing the page title without changing the slug? |
| 88 | +- Does the PR introduce a new page? If so: |
| 89 | + - Is the page using the right [page content type](/docs/contribute/style/page-content-types/) and associated Hugo shortcodes? |
| 90 | + - Does the page appear correctly in the section's side navigation (or at all)? |
| 91 | + - Should the page appear on the [Docs Home](/docs/home/) listing? |
| 92 | +- Do the changes show up in the Netlify preview? Be particularly vigilant about lists, code blocks, tables, notes and images. |
| 93 | + |
| 94 | +### Other |
| 95 | + |
| 96 | +For small issues with a PR, like typos or whitespace, prefix your comments with `nit:`. This lets the author know the issue is non-critical. |
| 97 | + |
0 commit comments