Reviewing pull-requests

Last updated on 2023-10-11 | Edit this page

Overview

What features does GitHub provide to facilitate reviewing pull requests?
What are the different options for the outcome of a pull request review, and when should I use each one?

After following this section, participants will be ready to practice the following skills:

create comments on particular lines and ranges of lines in the changes proposed by a pull request
suggest specific changes to a pull request
select the “approve”, “comment”, or “request changes” outcomes of a pull request review

reviewing PRs is one of the most important tasks for a Maintainer
the way you review a pull request, and communicate with the person who opened it, can have an enormous impact on their motivation to contribute again
GitHub provides several features that can improve your experience as a reviewer, and make it easier for contributors to follow up on your review

see the changes proposed in a PR via the Files Changed tab
if you want to comment on a particular line, hover your mouse over it and click the + symbol
comments can be added on their own, or as part of a Review: a commentary on the pull request as a whole
to comment on a range of lines, click-and-hold on the + for the first line in the range, and drag your cursor down the range, then release

as well as adding comments line-by-line, you can also suggest specific changes, e.g. to fix a typo, suggest improved wording, etc.
take the same approach to start a comment on a line or range of lines, then click the “add a suggestion” button, and edit the source content that appears in the input box
this makes it much easier for contributors to a) understand reviewers’ suggestions, and b) implement them

when you have finished commenting on particular lines, and suggesting changes, you can finish your review by clicking the “Review changes” or “Finish your review” button near the top-right of the screen
add general comments, a summary of your review, etc - don’t forget to thank them for taking the time to contribute! - and choose one of the three options:
- “Comment” - a general comment, with no firm outcome. Can be used to complete a review before a pull request is closed.
- “Approve” - approve the PR for merging. Some people use this when suggesting only very minor or optional changes - if you want to do this, make sure you are explicit about what changes you are suggesting etc before the PR can be merged
- “Request changes” - indicates that changes would be required to the PR before you would be willing to merge it.

You can add “saved replies” to your GitHub account
These can be used to automatically input a template response, on issues, PRs, etc
Use these if you find that you are often saying the same or similar things to people

What features does GitHub provide to facilitate reviewing pull requests?
What are the different options for the outcome of a pull request review, and when should I use each one?