5 Ways to Streamline the Pull Request Review Process

Few major projects are built or maintained by one person these days. Most collaborative efforts require multiple minds to come together into one seamless end product. That’s why pull request reviews are crucial to building for the web.

A pull request (PR) is an opportunity for contributors and maintainers to provide feedback on a piece of work before it gets merged with the main branch of a repository. It’s also an effective and efficient way for teams to achieve consistent and cohesive high-quality contributions. However, the pull request review process is a frequent bottleneck for teams as requests build up and work goes on hold, waiting for a review to be completed.

For this reason, finding even minor ways to streamline your pull request process saves your team time and effort. Anyone can help their development teams work more efficiently by implementing these optimisations. By doing so, you’ll make it easier for contributors to both make requests and review them. As the process becomes more streamlined, your team will be encouraged to collaborate more, which will help them create a better end product for your website visitors and customers. In this article, we share tips on how we guide introducing changes to Calibre’s codebases.

Keep code understandable and standardised

One of the best ways to make pull requests easier to review is to ensure code is as readable as possible. This way, it’ll be simple for the reviewer to breeze through the code and spot places for improvement when it comes time to review.

It holds up the review process if the reviewer has to ask for clarification on a particular line or function. Plus, when code is easier to understand, it makes it easier for future team members to come in and make changes as necessary.

Our tips to make code easier to understand for everyone include:

• Enforcing standard naming conventions, consistent indentation, and file organisation practices.
• Adding comments to describe what a particular piece of code does.
• Discouraging long functions or deep nesting so the code is more legible.
• Coding with both DAMP and DRY principles in mind so that the code is concise while still being easily readable.
• Using a tool like Prettier to automatically standardise the code to avoid confusion or arguments over style choices.

Use pull request templates

Writing easily reviewable pull requests is an art that takes time to perfect. Instead of relying on everyone to figure out how to create better pull requests on their own, use templates to make an impact right away.

It’s easy for people to forget that the reviewer may not know what’s going on in the PR creator’s head. However, without that crucial context, the reviewer won’t be able to do their job correctly. A good pull request review template organises the creator’s thoughts and ensures they’ve included all the relevant information reviewers need. A template saves everyone time, as PR reviewers and creators don’t need to ask and give that information later.

As a bonus, it makes writing and reading the review request far more straightforward. Writers need to fill in a form, and reviewers can scan for what they need since they’ll be familiar with the format.

Here’s what we focus on in our pull request template:

• Reminding creators that their code should be short and focused on one objective to save the reviewer’s time.
• Providing a space for screenshots and metrics that prove why and how this contribution is an improvement.
• Requiring a complete description of the review, including any prerequisites or required actions outside the PR that we must complete before it’s merged or released.

If you’re unsure where to start, check out our Pull Request Review Template. We also created issue templates, which can be helpful in managing requests for open source projects. Use them for free, or make them your own to fit your organisation’s needs!

Automate performance reviews

As a web performance company, we implement speed monitoring as early as possible in the development process. One of the easiest ways to save people’s time on profiling performance is to automate pull request performance reviews. A Pull Request Review will pinpoint performance changes your team should expect from this addition or removal. They can then use this information when evaluating the PR itself:

For instance, if a pull request contains code designed to improve Core Web Vitals by altering the load priorities of a page, it’d be helpful to know if those changes affect performance. The pull request creator can cancel their request if the code doesn’t create a noticeably faster page. Not only will that save the creator time waiting for a review, but it’ll also save the reviewer time providing feedback on a pull request that the team won’t merge.

Automating performance reviews on pull requests also helps your team by:

• Preventing them from shipping regressions by mistake.
• Allowing them to experiment to find new ways to improve web performance.
• Making it easier to evaluate the efficacy of a pull request, as the data is right there.

Establish clear guidelines for providing feedback

Feedback helps people improve, but giving good feedback is easier said than done. It’s not easy to know what needs to be reviewed and what good feedback looks like.

It’s best to take the mystery out of the review process by laying out explicit guidelines on what reviewers should look for in each PR. A checklist is an excellent place to start, as reviewers can review the list and see whether the work they’re checking achieves what it needs. Clearly laying out these standards makes it easier for the PR creator to ensure their contribution meets the standards before submitting it for review.

Teams should also create guidelines for what helpful feedback looks like. If the reviewer wants to leave a suggestion on how to improve the code, they need to make sure the feedback will lead to a better outcome. Not only will that save time, as no one needs to follow up for a further explanation, but it also makes the review process less arbitrary for the developers.

Good feedback should include the following:

• Clear, actionable advice with examples of what should be changed.
• Reasons for why the changes have been suggested, with documentation or evidence that supports that point of view.
• An impersonal tone, so the review does not feel like overt criticism.

Set up a process for getting requests reviewed quickly

Opening a request and completing it must be as straightforward as possible to reduce bottlenecks. Instead of relying on a messy ad hoc messaging system that gets lost in inboxes, creating something more automated and organised is far better.

One way to improve your system is to integrate the process with your current tools. For instance, teams on Slack could create a PR channel that automatically updates as soon as new PRs are opened for review. This way, reviewers get notifications where they’re already active:

To ensure the pull request review process runs more smoothly we also:

• Establish smaller teams that review each other’s requests, so no one has to shoulder all the work.
• Configure the GitHub CODEOWNERS file to alert project reviewers of a new review automatically.
• Set up fallback plans in case team members cannot work on requests immediately, so urgent requests aren’t holding back progress.
• Implement GitHub branch protection rules to make it impossible to release broken code without first passing a pull request or receiving signed commits.

Harness the power of your team

The greatest asset any company has is the people within it. For this reason, companies must create and nurture an environment where everyone is a part of the solution. This is true for the pull request review process and is also valid for improving web performance in general.

In many companies, web performance is still the domain of developers. This approach puts a significant burden on a single team and limits what they can accomplish. By creating a space where your entire company has the opportunity to help improve performance, you ultimately make a far better experience for your visitors. Learn more about how to harness your whole team with these guides:

• How to Convince Your Boss to Care About Speed
• How to Plan and Deliver on Site Speed as a Team

Ben Schwarz

Ben is the Founder and CEO of Calibre. He uses his experience in far-reaching Open Source projects and web standards to build tools for a better, more accessible web. Find him on Mastodon or LinkedIn.