Writing better pull requests is one of the best improvements you can make as a software engineer. Well written pull requests create a smoother review process, help get your PRs merged faster and increase the level of trust and respect you earn from your team. This guide will present several easy to implement ideas that will help you write better pull requests.
Keep Notes
A well-written pull request starts from the moment you start work on an issue. Create a new text file for every issue you start work on.
Use this file to keep notes on anything important that helps give context to code reviewers. This could be things like:
- weird errors you run into and figured out a way around
- design decisions made when choosing between multiple paths
- discussions and decisions made with stakeholders that took place in private
Keep notes as information is acquired. Otherwise, it’s easy to forget details when making the PR. These notes are not only helpful for creating the pull request, they also come in handy months later when someone across your code and has questions. Pulling up this file helps jog your memory quickly and can get you back into the mindset you had while working on the issue.
Squash Commits
Commit often while working on an issue. Make a commit when you’ve accomplished something towards the issue’s goal, no matter how small. When it comes time to finishing off the ticket and making the PR, squash all those commits into one. Nobody wants to see 5 commits that say “fix typo” in the PR. Making one squashed commit helps provide a cleaner PR for people to review.
There are a couple exceptions to this.
1. Never change “public” commits
A commit is public when someone else has been exposed to it. Don’t cause issues for them by changing the git history they’ve seen. If your PR is still in draft and you haven’t yet added reviewers, you can go ahead and change the history because there is no expectation from others that the PR is in a ready state.
If you are making changes based on code review comments and you make several local commits but haven’t pushed them yet, it’s fine to squash those local commits all into one because they are not yet public.
2. Leave multiple commits if it helps code review
Deliberately having multiple commits in a PR comes in handy when moving code. It’s difficult to review code where the code has moved to a different file and then changes were made afterwards. It’s easy to introduce bugs in these cases that may go unnoticed.
In this case, make one commit that only moves the code. Then make a 2nd commit with changes. In the PR description call out what you’ve done and encourage the reviewers to look at the individual commits. The first commit will show that the code has been moved as is. Reviewers can focus their effort on the 2nd commit with the changes.
If you are moving a lot of code, make a separate PR. However, if it’s only one or two functions, it makes sense to combine the changes in one PR.
Write Pull Request Description as your Commit
When making the last commit, write your commit message as the PR description. Github and Bitbucket encourage this behaviour. Your commit message automatically goes into the Pull Request description. This saves time from having to write two different messages.
If there is additional information that is only relevant to the PR, append it to the description or add it as a comment ie. creating a demo video of the change. Something like this doesn’t fit well in the commit message so append it to the PR separately from the commit.
Have Your Own Template
If your team doesn’t have a PR template or format to follow, you should have one for yourself. People will get used to your format after a few reviews and come to expect it. Having a standard format helps people to know what to expect if they’re added to your PR.
Always include the JIRA ID in the PR title ie. [JIRA-123] Add Feature Widget. Use the JIRA title as the PR title, perhaps with some brevity modifications to fall into the 50 character recommendation for a commit title.
The PR description must provide all the context a reviewer needs. You can include additional links if you assume reviewers will not follow them. Links should only contain additional information beyond the scope of the PR. Include all details in the description. It’s ok to copy & paste from other links.
Write in full sentences. If you have trouble getting started, a good prompt is “This PR…”. Refer back to your notes to include additional context for any decisions made.
Screenshots or videos help reviewers feel confident that the changes have been tested properly.
Annotate
Review your notes to see if there’s any lines of code that should be annotated. with additional context. Add comments to your own PR for these cases.
During this process, ask yourself, “Is this a comment that is truly only applicable during the code review or would it make sense to put this comment in the code?”. If it makes more sense to include as a code comment, add another commit that does so.
Use comments to guide reviewers toward the main code to review. For example, in a PR which contains one small main code change and a number of secondary changes scattered in different files, it’s helpful to make a comment at the main code change saying “This is the main change”. It helps reviewers know where they should start their review and where they should focus on.
Wait 25 Minutes
Now that your pull request is setup and you’re ready to add reviewers to it, don’t. Wait at least 25 minutes. The more time you can let pass, the more benefit you’ll get from the next step.
Let some time pass so you can look at the PR and code changes with a fresh set of eyes. You want to review the pull request as if you were not involved in the creation of it. Wait overnight if you can. I’ve noticed that when I’ve waited overnight I’ve have insights into how to better structure the code and have caught bugs.
Self-Review
After you’ve waited, self-review your PR. Imagine this was someone else’s code and you have no initial context about the changes that were made. Go through the PR as if that were the case.
Start by reading the PR description to understand the issue. Read everything that is written down. Make edits immediately for anything unclear. Try to remove unnecessary extra words. A short sentence is more readable than a longer sentence. Check that the voice is consistent throughout the text. These are little details but they help other people understand your writing better. Better understanding means less time spent on clarification.
After you understanding the context from the description, move on to the code. Review it normally and see if anything could be improved or if you have questions about anything. If you are unclear about anything, reviewers will be as well. Add more comments as needed.
If changes are needed, push a squashed commit and then repeat the process again for the changes.
Wait For Green Checks
Once everything looks good, wait until all PR checks are green. Don’t add reviewers before this. Adding reviewers signifies that the PR is ready to go as is.
Add Reviewers
Now your PR is ready to be reviewed. Some teams will have guidelines or rules about how to add reviewers. If your team doesn’t, here are some guidelines.
Add 2 or 3 reviewers. If you add more than this, the review starts to fall into the tragedy of the commons trap where reviewers might wait on other people.
Have a purpose for each reviewer that you add even if you don’t mention it. Choose at least one person who knows the code area fairly well.
If the change is fairly risky, call that out. Add a comment after adding the reviewers to let them know - “I added @alice and @bob because you’ve both dealt with security issues in this area before.” This primes the reviewers to know what they should be looking for. It also lets reviewers know that you’ve put thought into choosing them and why they are on your PR.
Conclusion
Taking a little bit of time to prepare your pull requests goes a long way to helping you and your team. Just as with programming, a little thoughtfulness up front saves a lot of time down the road. You won’t spend as much time answering code review questions as you used to. Your pull requests will be reviewed faster, you’ll have less bugs and you’ll gain the respect of your teammates. Your pull requests will be used as models for how PRs should be done.