TL;DR#
Along with catching bugs and regressions, PR reviews are a high value-add to our clients and a source of continued learning for our team.
Background#
When we write code for projects, it isn't immediately pushed live. Instead, each chunk of work is submitted for peer review in a "pull request" (PR).
The Problem#
We're all human, and the code we write could have bugs, regressions, or sub-optimized queries.
The Solution#
To increase the chances that we're writing bug-free, optimized code it is vital that we get multiple sets of eyes on every bit of code that ends up on the production site. Therefore, when anyone on the team submits code in a pull request, a link to the PR is shared in the #pull-request channel of our Slack team along with the language(s) involved and a brief summary of the work. All engineers subscribe to the #pull-request channel and are expected to review a few PRs per week. When an engineer decides to review a pull request they react to the Slack post with an emoji to alert the team that the PR is being reviewed (though it is still encouraged that other engineers also review the work). Once a PR is approved by a reviewer on Github it is free to be merged.
How does a pull request review work, step by step?#
A pull request review moves through steps, from the author's own check to the merge. The author checks the work, groups the commits, writes a description and opens the pull request. A reviewer then claims it, reviews it and submits a decision, the author answers the feedback, and the approved pull request merges.
- Check your own work. Gnar's post Our Code Review Process: More than Quality Assurance says an author should first look through a "reviewer's lens," "helping them catch small items they overlooked".
- Group the commits. Gnar's post Committing code at The Gnar Company suggests that an engineer "group their commits into logical, atomic commits to help others who donate their time to review the work".
- Write the description. Google's guide to change descriptions says a description should answer "What change is being made?" and "Why are these changes being made?" The Gnar commits post asks each commit description for the same two answers, under "This commit" and "Why?".
- Open the pull request. On GitHub, a pull request template can put those prompts in front of contributors: they "will automatically see the template's contents in the pull request body". One accepted file name is
.github/pull_request_template.md. GitHub says templates "are available to collaborators when they are merged into the repository's default branch". - Claim it. In Gnar's process in the Solution section above, a reviewer who picks up a pull request will "react to the Slack post with an emoji to alert the team that the PR is being reviewed".
- Review and decide. GitHub's pull request review reference gives three decisions. Comment "Leaves general feedback without explicitly approving or requesting changes". Approve "Signals that the changes are ready to merge". Request changes "Flags feedback that the author should address before merging".
- Answer the feedback. The Gnar commits post handles review comments in follow-up commits with messages such as "Address PR feedback", "so that reviewers can see the specific changes that were made related to their comments".
- Merge. The Solution section above ends its process with the merge: "Once a PR is approved by a reviewer on Github it is free to be merged".
What should a reviewer look for in a pull request?#
Google's guide to what to look for in a code review starts with design: "The most important thing to cover in a review is the overall design of the CL". This post names the risk a review guards against: "the code we write could have bugs, regressions, or sub-optimized queries".
The guide calls a change a CL, short for "changelist". Its glossary says other organizations often call this a "change", "patch", or "pull-request". Three of the lines in the guide's summary:
- Design: "The code is well-designed".
- Tests: "Code has appropriate unit tests".
- Test design: "Tests are well-designed".
On tests, the guide asks a question: "Will the tests actually fail when the code is broken?" Its standard of code review sets the bar for approval. Reviewers "should favor approving a CL" once it "definitely improves the overall code health of the system", even if it "isn’t perfect".
Google's guide also says to "compliment developers on good things that they do". Gnar's code review post has a section headed "Reviewers: Celebrate Positive Code". It says: "Celebrating each other's moments of brilliance, no matter how big or small, is validating, motivating, and inspiring".
How should reviewers write comments, and how should authors answer them?#
Reviewers should write kind comments about the code, give the reason and mark which points are minor. Authors should answer each comment, including the ones they decline. Gnar's code review post frames every comment this way: "Unless the changes are going to break something, every reviewer comment is meant as a suggestion, meaning authors aren't required to accept the reviewer's changes".
For reviewers, Google's guide to writing review comments starts its summary with "Be kind" and "Explain your reasoning". The Gnar post agrees that "the reviewer should explain the 'why' behind their suggestion".
Google's guide also suggests "labeling the severity of your comments, differentiating required changes from guidelines or suggestions". Its first example reads: "Nit: This is a minor thing. Technically you should do it, but it won’t hugely impact things". The Gnar post uses the label "NIT" (as in nitpick) for a minor suggestion.
For authors, the Gnar post says it is "still important for the author to close the loop on communication". The author should "let the reviewer know if they have accepted a suggested change or not".
How big should a pull request be?#
Google's guide to small changes says "the right size for a CL is one self-contained change". It gives a rough line count: "100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large, but it’s up to the judgment of your reviewer".
The guide is clear that this is not a fixed limit: "There are no hard and fast rules about how large is “too large.”" The guide adds that file count matters too: "A 200-line change in one file might be okay, but spread across 50 files it would usually be too large".
Two more lines from the guide shape what goes into a change. "The CL should include related test code". And "It’s usually best to do refactorings in a separate CL from feature changes or bug fixes". The guide also says "reviewers have discretion to reject your change outright for the sole reason of it being too large".
Gnar's code review post splits work before it reaches review: "To keep larger projects from stalling, we break them down into the smallest units possible".
How long should a pull request review take?#
Google's guide to review speed sets a limit on responding to a review request: "One business day is the maximum time it should take to respond to a code review request (i.e., first thing the next morning)". Its focus is "the response time", "as opposed to how long it takes a CL to get through the whole review and be submitted". Google says following its guidelines means "a typical CL should get multiple rounds of review (if needed) within a single day".
The guide says: "If you are in the middle of a focused task, such as writing code, don’t interrupt yourself to do a code review". It gives a busy reviewer three ways to reply: say "when you will get to it", "suggest other reviewers who might be able to respond more quickly", or "provide some initial broad comments". Gnar's Solution section above spreads reviews across the whole team: "All engineers subscribe to the #pull-request channel and are expected to review a few PRs per week".
For a change too large to review soon, the guide says your "typical response should be to ask the developer to split the CL into several smaller CLs that build on each other".
How do you require pull request approvals on GitHub?#
GitHub's steps for managing a branch protection rule say to select "Require a pull request before merging", and then: "Optionally, to require approvals before a pull request can be merged, select Require approvals". The same page then says to select the "Required number of approvals before merging" dropdown menu, then click "the number of approving reviews you would like to require on the branch".
GitHub's page on protected branches says: "Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations. Protected branches are also available in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server".
A branch protection rule can require "that all pull requests receive a specific number of approving reviews before someone merges the pull request into a protected branch". GitHub's page on approving with required reviews adds: "Pull request authors cannot approve their own pull requests".
The Gnar Company's code review post states its golden rule plainly: "the reviewer who provides final approval cannot be the author".
These optional branch protection settings decide what must happen before a merge:
| Setting | What GitHub's docs say it does |
|---|---|
| Dismiss stale pull request approvals when new commits are pushed | Dismisses approvals "when commits are pushed that affect the diff in the pull request". |
| Require review from Code Owners | "any pull request that affects code with a code owner must be approved by that code owner". |
| Require approval of the most recent reviewable push | The latest push "must be approved by someone other than the person who pushed it". |
| Require conversation resolution before merging | "Requires all comments on the pull request to be resolved before it can be merged to a protected branch". |
| Require status checks to pass before merging | "all required status checks must pass before collaborators can merge changes into the protected branch". |
A Request changes review blocks a merge only when a rule says so. GitHub says the option "is purely informational and will not prevent merging unless a ruleset or classic branch protection rule is configured with the 'require a pull request' option".
How do you route a review to the right person on GitHub?#
A team can route reviews by hand in a chat channel, or let GitHub request reviewers through a CODEOWNERS file or team auto assignment. Gnar's process in the Solution section above uses the chat channel, and a claimed pull request stays open to others: "it is still encouraged that other engineers also review the work".
| Route | How the reviewer is chosen | Where it is set up |
|---|---|---|
| Chat channel (Gnar) | A reviewer claimed the pull request with an emoji on the Slack post. | The #pull-request channel in the team's Slack. |
| CODEOWNERS file | GitHub requests review from the owners of the code a pull request changes. | A file named CODEOWNERS in the .github/, root or docs/ directory. |
| Team auto assignment | GitHub swaps a requested team for members picked by round robin or load balance. | The team's code review settings. |
GitHub's page about code owners says the file lets you "define individuals or teams that are responsible for code in a repository". It says: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own". Drafts are the exception: "Code owners are not automatically requested to review draft pull requests".
GitHub's page on code owners says: "You can define code owners in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server".
GitHub's page on team code review settings says: "Code review settings are available in all public repositories owned by an organization, and all private repositories owned by organizations on GitHub Team, GitHub Enterprise Server, and GitHub Enterprise Cloud".
Team auto assignment works on requests to a whole team. When it is on, "the team is removed as a reviewer and a specified subset of team members are assigned in the team's place". When code owners are requested automatically and a branch protection rule requires code owner review, "the team request cannot be removed and so the individual request will appear in addition to the team". The round robin algorithm picks by "who's received the least recent review request". The load balance algorithm "chooses reviewers based on each member's total number of recent review requests and considers the number of outstanding reviews for each member".
The Outcome#
Along with catching bugs and regressions, these peer reviews have been a great source for continued learning across the team. Both reviewers and the author of the PR have an opportunity to learn new languages, syntax, code patterns, and optimizations. Peer code reviews also help our team gain context across projects and provide a great benefit to clients who are getting help from the team as a whole, as well as the engineers dedicated to their project.
Why does code review help a team learn?#
Code review helps a team learn because it passes knowledge between the people who write and read the code. A 2013 Microsoft Research study found that "while finding defects remains the main motivation for review, reviews are less about defects than expected". It found that reviews "instead provide additional benefits such as knowledge transfer, increased team awareness, and creation of alternative solutions to problems".
The authors of that study "observed, interviewed, and surveyed developers and managers" and "manually classified hundreds of review comments across diverse teams at Microsoft".
Google's standard of code review treats teaching as part of the job: "Code review can have an important function of teaching developers something new about a language, a framework, or general software design principles".
Gnar's code review post widens who does the reviewing: "In fact, in some cases here at The Gnar, the reviewer is not even working on the same project". The post adds that this "also gives clients access to the whole team's collective knowledge and expertise".


