How To Create Pull Requests Which Are a Pleasure To Review?
A few tools and templates to stay on top of pull requests
If you’re reading this blog post, you have probably felt the pain of a 4,000 line pull request with no description or context.
No one should roll their eyes and groan upon opening a pull request. If you share the belief that the onus of making them a pleasure to review is on the engineer putting up the pull request, read on.
Pull Request Templates
We’ve recently started using pull request templates at our company. Pull request templates provide a template for the engineer to fill in when writing a pull request.
We don’t enforce descriptions in pull requests however I’ve found if you include a template the engineer will likely fill the fields out and provide the reviewer with some context.
This is especially useful when you are reviewing a feature/project you’re not currently working on. To add a template to your project you’ll have to create a pull_request_template.md file, this can be visible at the root of your project or hidden inside a .github/ directory. Here’s the template we’ve adopted:
This template is useful as the engineer thinks about the change they’ve made in plain English, thus making the pull request clearer for the reviewer. More information about pull request templates can be found here.
Restrictions on Pull Request Sizes
Imposing a size limit makes pull requests more concise, and easier for the reviewer to digest meaning they may be able to catch any potential mistakes, using less effort.
The relationship between cognitive load and the size of the pull request is exponential — at a certain size, the reviewer won’t even read the code and bugs will slip through.
To combat this we’ve imposed a size limit of 400 lines of code on pull requests. Under this limit, we sometimes need to break down features into multiple pull requests (i.e SQ4–123-a, SQ4–123-b, SQ4–123-c, etc.) and have found code review more effective in doing so.
The commit history does become slightly messier however we feel it’s a worthy tradeoff; the less the reviewer has to think about, the more they’ll catch in the review.
A 400 line limit might not be right for your project. There’s an interesting tool here which benchmarks your organization against others in the industry.
What Tools To Use On GitHub
There are several code pull request tools that make reviewing code that much easier. Here are a few of my favourites:
- Reviewable — This organises the review in a nicer UI than Github’s native view, it has plenty of keyboard shortcuts to aid when reviewing. You can also review by commit if you want using Reviewable.
- GitHub.dev — Did you know that if you press
.whilst on a GitHub repo you’ll be taken to a web version VSCode? This works for pull requests as well, you can clearly see all the files changed and make comments in IDE as you please. - Better Pull Request for GitHub — Similar to above this chrome extension will let you browse the files changed in an IDE-like tree structure.
- Codacy — You’ll be able to remove mundane code review activities (such as code style) with this GitHub application which automates some aspects of code review.
- Pre-commit/pre-push hooks using Husky — these tasks that are run locally before you commit or push code; they can do such things as run tests, run lint checkers and check commit messages and they’ll catch things that could have otherwise slipped through. This should simplify the code review for the reviewer.
Self-review
It’s always worth considering; would you enjoy reviewing your own pull request?
This is a technique that I use personally. As silly as it seems, I pretend that I’m the reviewer and review the code I’ve pushed myself first before asking anyone else to.
I leave comments for myself and resolve them once I’ve fixed them. Even with all the tools I’ve written about above I still catch things in reviewing my own code. After that, I’ll then request a review from somebody else and hopefully, I’ve made it more pleasant for them, as well as reduced what could have been missed before it is merged in.
With these tools in your arsenal, you can make pull requests less painstaking, maybe even enjoyable, for the reviewer. If you have any more suggestions, please let us know. We love to hear and explore new ways to improve our process.
Originally published at https://www.brightec.co.uk.
