What are the Best Tools for Pull Requests?
Do you subscribe to the philosophy that pull requests should be a pleasure to review? This blog explores several ways in which this can be achieved.
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.
GitHub Pull Requests: The Best Tools
There are several code pull request tools that make reviewing code that much easier. Here are a few of my favourite GitHub pull requests:
Reviewable
Reviewable 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 the full stop key 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, Better Pull Request for GitHub is a chrome extension that lets you browse the files changed in an IDE like tree structure.
Codacy
Codacy automates some aspects of code review which can be extremely helpful. With Codacy, you’ll be able to remove mundane code review activities (such as code style) and streamline the often time-consuming task of coding new applications.
Husky
Pre-commit/pre-push hooks using Husky. These tasks are run locally before you commit or push code; they can do things such as run tests, run lint checkers and check commit messages and they’ll catch things that could have otherwise slipped through. Husky should help to simplify the code review for the reviewer.
Our Pull Request Template
We’ve recently started using pull request templates at Brightec. 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 have found that 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 pull request template we’ve adopted (click raw to see the raw markdown file):
This pull request 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. Learn more about pull requests templates 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. Afterall, 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 which benchmarks your organisation against others in the industry.
Would You Review Your Own Pull Request?
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 do so. I leave comments for myself and resolve them once I’ve fixed them.
Even with all the pull request tools I’ve written about above I still catch things in reviewing my own code. I’ll then request a review from somebody else and hopefully I’ve made the reviewing process more pleasant for them, while reducing what could have been missed before it is merged in. It’s one of the ways I get the best out of code reviews.
Final Words
With these Pull Request 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.
Looking for something else?
Search over 400 blog posts from our team
Want to hear more?
Subscribe to our monthly digest of blogs to stay in the loop and come with us on our journey to make things better!