Reviewing pull requests

Reviewing documentation pull requests is a great way to introduce yourself to the Kubernetes community. It helps you learn the code base and build trust with other contributors.

Before reviewing, it’s a good idea to:

  • Read the and style guide so you can leave informed comments.
  • Understand the different in the Kubernetes documentation community.

Before you start a review:

  • Read the CNCF Code of Conduct and ensure that you abide by it at all times.
  • Be polite, considerate, and helpful.
  • Comment on positive aspects of PRs as well as changes.
  • Be empathetic and mindful of how your review may be received.
  • Experienced contributors, consider pairing with new contributors whose work requires extensive changes.

In general, review pull requests for content and style in English. The figure below outlines the steps for the review process. The details for each step follow.

.mermaid { display:none; }

[JavaScript must be enabled to view content]

Figure - Review process steps

  1. Go to . You see a list of every open pull request against the Kubernetes website and docs.

  2. Filter the open PRs using one or all of the following labels:

    • (Recommended): PRs submitted by contributors who have not signed the CLA cannot be merged. See Sign the CLA for more information.
    • language/en (Recommended): Filters for english language PRs only.
    • : filters for PRs of a certain size. If you’re new, start with smaller PRs.

  3. Once you’ve selected a PR to review, understand the change by:

    • Reading the PR description to understand the changes made, and read any linked issues
    • Reading any comments by other reviewers
    • Clicking the Files changed tab to see the files and lines changed
    • 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.

  4. Go to the Files changed tab to start your review.

    1. Click on the symbol beside the line you want to comment on.
    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).

When reviewing, use the following as a starting point.

  • Are there any obvious errors in language or grammar? Is there a better way to phrase something?
  • Are there any complicated or archaic words which could be replaced with a simpler word?
  • Are there any words, terms or phrases in use which could be replaced with a non-discriminatory alternative?
  • Does the word choice and its capitalization follow the ?
  • Are there long sentences which could be shorter or less complex?
  • Are there any long paragraphs which might work better as a list or table?
  • Does similar content exist elsewhere on the Kubernetes site?
  • Does the content excessively link to off-site, individual vendor or non-open source documentation?
  • 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?
  • Does the PR introduce a new page? If so:
    • Is the page using the right page content type and associated Hugo shortcodes?
    • Does the page appear correctly in the section’s side navigation (or at all)?
    • Should the page appear on the listing?
  • Do the changes show up in the Netlify preview? Be particularly vigilant about lists, code blocks, tables, notes and images.

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.