January 12, 2023
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.
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:
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:
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!
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:
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:
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:
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:
Join thousands of subscribers keeping up-to-date with web performance news and advice.
Engineering Manager at Google Chrome