Reviewing Pull Requests

Review a Pull request

Anyone can review a documentation pull request (PR). Visit the Pull requests section in the Spinnaker website repository to see a list of all currently open pull requests.

Reviewing documentation pull requests is a great way to get started contributing to the Spinnaker community. It helps you to learn the code base and builds rapport with other contributors.

Before you begin

Before reviewing documentation, do the following:

Read the documentation style guide so that you can leave informed feedback.

  1. Review the Code of Conduct and ensure that you abide by it at all times.
  2. Be polite, helpful, and considerate of others.
  3. Comment on positive aspects of a PR, as well as changes.
  4. Be empathetic and mindful of how your changes or review may be received.
  5. Ask clarifying questions if something in a PR is unclear.
  6. Assume positive intent.
  7. If you are an experienced contributor, consider pairing with new contributors whose work requires extensive changes.
  8. Be mindful of the needs of contributors that are neurodivergent or have a learning disability. Ask your fellow contributors how they work best and what communication style they prefer.

Start the review process

  1. Go to (https://github.com/spinnaker/spinnaker.io/pulls) to see a list of all current open PRs in the Spinnaker repository.

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

  • Beginner friendly
  • Help wanted
  • Questions
  • no-lifecycle

PRs have two states, one is ready for review and the other is a draft Pull request

If a PR is classified as a draft pull request , this means the contributor would like feedback on their PR throughout the review process, and that the PR is not ready for review or merging.

Reviewers should encourage new contributors to make use of draft PRs when appropriate.

If a PR is ready for review, reviewers should proceed to the next step in the review process.

  • Once you’ve found a PR to review, understand the change by:

    • Reading the PR description to learn why the PR was made, and read any linked issues attached to the PR
    • Reading comments left by other reviewers
    • Clicking the Files changed tab to see any files and lines changed
  1. Go to the Files changed tab and begin your review
  • Click on the + symbol beside the line you want to comment on.
  • Fill in any comments you have about the line in question, and click either, Add a single comment (if you have only one comment to make on the PR) or Start a review (if you have multiple comments)
  • When you’ve finished reviewing the PR, click Review changes at the top of the page. Here, you can add a summary of your review (and leave some positive comments and thanks for the contributor!), approve the PR, comment or request changes as needed. New contributors should always choose Comment.

Reviewing checklist

When reviewing a PR, use the following questions as a starting point:

  • Are there any obvious errors in grammar or language?
  • Is there a better way to phrase something?
  • Are there words, phrases, or terms that should be replaced with a non-discriminatory alternative?
  • Does the word choice, punctuation, and capitalization follow the style guide ?
  • Are there long sentences which could be shorter or made less complex?
  • Are there long paragraphs which would work better as a bulleted list or table?

Other

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.

Last modified July 13, 2021: docs(site): add 404.html and fix docs contrib section (#117) (df60766)