The review process

TODO: Update title

TODO: Intro paragraph

Your PR is now passing CI.

tl;dr - Following a PR

This quick overview outlines the steps you'll need to complete following submission of your pull request.

1. Wait for a review.
2. Respond to feedback.
3. If changes are requested:
4. Work through completing requested changes.
5. Submit all requested changes.
6. Re-request a review when all requested changes have been submitted.
7. Repeat section three until no further changes are needed.
8. Wait for your PR to be approved and merged. Congratulations!

I submitted my pull request, what now?

After submitting your pull request, you'll need to wait for the review process to begin. There are two sides to the review process: providing a review and receiving a review.

Providing a review

TODO: Intro.

/// info | Review expectations

You should expect the following from anyone reviewing your submissions, and you should engage in the following when you are reviewing submissions from others.

///

TODO: segue.

Before engaging in a review, THINK. As reviewers, we should consider whether the response we're about to send is:

• True. Always strive to provide accurate suggestions and information.
• Helpful. We are providing guidance on how to improve the submission; this guidance should clearly identify the source of a problem or an unconsidered use case, and ideally provides a path forward for what would resolve or satisfy the concern.
• Inspiring. It is up to us to inspire the author to want to work through our requested changes.
• Necessary. The expectation is that the author will read everything we post; we must respect their time and effort by only posting necessary replies.
• Kind. There are multiple ways to present the same feedback; we need to ensure we are choosing to be kind, supportive, and constructive with our words.

if the code does something particularly clever, or introduces an API that you didn't know about, when in the middle of a PR where everything is going wrong, pointing out a positive part of the contribution.

Receiving a review

Receiving a review involves three basic steps:

1. Initial feedback and questions.
2. Change requests.
3. Approval and merge.

Each step is detailed below. If at any point during the process you have questions, don't hesitate to ask! We are happy to help.

Timeline and initial feedback

We aim to begin a review within ten business days, however, with more complicated submissions, that timeline may be extended.

We typically maintain continuity with reviewers on each pull request, which is to say, you'll likely work with the same reviewer for your entire review. This provides a smoother experience for everyone involved. This means your reviewer will have context throughout the process, and you'll be able to learn what to expect in terms of response cadence and review style.

There are often initial comments or questions from a reviewer to establish context for and understanding of the pull request. You may receive some initial questions, such as the following. Have we understood correctly what this contribution is meant to be doing? Can you explain this edge case we've identified?

You can expect us to respond to each exchange within a rolling ten business day time frame. Responding to feedback and questions is an essential part of the review process. We will expect a response from you before we move to the next step in the process.

Change requests

Most of the time, your reviewer is going to request changes on your pull request. This isn't a reflection of your work, it's simply part of the process.

Work through requested changes

Your reviewer will post comments to your PR. These comments can be general, on a specific file, or on a specific line or lines of code. They will sometimes include directly suggested changes that you can apply to your PR through the GitHub UI. Typically, they will be questions, requests for clarification, or guidance on updates.

Submit all requested changes

If an issue is particularly complicated, and fixing one will impact another thing, you can ask for a review on the specific piece you've updated. Be sure to specify exactly what you're looking for.

Re-request a review

Once you have resolved all the requested changes in a given review, you can re-request a review from your reviewer.

Repeat the three steps above until no further changes are needed.

Pull request approval and merge

Once the change requests are completed, the PR will be approved. In most cases, we will immediately merge it. In some cases, there may be extenuating circumstances, such as relying on another not-yet-merged PR, that will lead to a delay. We'll communicate this in the comments, so you'll know the situation.

The next step is the release process.