6 Easy steps for Better GitHub pull requests
It’s 4pm, and after a good day’s work, I finish building my new feature, commit it, and push up to my feature branch. After opening the pull request on GitHub to be merged back into master, I give myself a pat on the back and head home.
An email arrives into the team’s inbox. Adrian wants to merge 37 commits into master: 28 files changed, +1120 -410, with the title “Add new feature” and no description. Time for a coffee…
It may take us a few more minutes to make a good pull request, but it can dramatically speed up and help the people who are doing the reviews.
As well as good coding practices, here are a few things I’ve found that help make the pull request process smoother for my team.
1) Easy on the eye
I set a line width of 80 on my editor, and use spaces over tabs, to help us keep our codes shorter in length.
It adds friction for the reviewer who needs to go through your changes if they need to be constantly scroll left to right, or watch out for the indentations over a multiple wrapped line.
I prefer spaces because they render shorter compared to tabs in GitHub’s diffs side-by-side comparison.
2) Keep it small and focused
I find the size of the pull request has the biggest impact on the time and effort required for it to be accepted for merging (or rejected).
Bigger pull requests requires the reviewer to set aside a dedicated time to go through the changes.
While working on your new feature, it may be very tempting to refactor something you come across, or to reformat existing code. However this adds extra changes and concerns to your pull request, which usually ends up adding noise over your real changes for your PR’s objective, slowing down the discussion that could take place on the main goal of the pull request.
If your feature has multiple objectives or goals, ask yourself if they can be reviewed in smaller chunks. If so, you can submit your pull request into a feature branch instead of master.
3) Time travel with good git comments
Having a good git commit history allows you and others to travel back in time quickly without having to dig through the code diffs, or blindly jumping back and forth until you get to the right time. It makes it easy for someone to revert or cherry pick changes as well.
Generally I prefer to only rebase when I pull from the same branch, and create a merge commit when pulling from other branches. i.e. merging master into the current working branch.
4) Write a description
The pull request description is the most useful place to inform and help the reviewer with important information about your changes. Please don’t skip this part~!
How to be useful here very much depends on the nature of the changes.
Does your pull request contain any styling or visual changes that users can see? It would be very helpful to provide screenshots 📸 of what the reviewer is expected to see. (Bonus points for before and after screenshots, or GIFs for UI interactions or animations.)
Providing links gives reviewers a quick click away to your changes, these can be url, file, assets paths the changes are on. Don’t forget to reference back to GitHub issues or comments if applicable, so they can see where the intent of your changes stem from.
Tag and label your pull request, if you have access to it lets use it~! Is your pull request a bug fix? Use the labels on the right to let others know instantly what category your changes are for.
If your pull request is time sensitive or not quite ready to be merged yet, let others know in the description. You can provide a to-do checklist, which GitHub will pick up and show before you even jump into the PR:
5) Review it yourself
After opening your pull request, don’t forget to review it yourself too. There have been many times where I’ve spotted things I missed or got wrong just from doing this step. This will save your reviewers time and energy. Also provide comments on your own changes where you think they will be helpful.
“This line is the cause of the bug because…”
6) Communicate
In a professional work setting during discussion happening in the PR, if it results in more than three back-and-forth comments, I’ll try and speak to the person face to face or over a call if possible. I’ve found this to be much faster to resolve concerns and come to an agreement, instead of seeing chains of lengthy discussion over days, which at that point the master branch has moved on, and now you have merge conflicts.
Don’t forget to summarise the result of your discussion on the pull request for future reference.
Thanking someone at the end of the review process goes a long way, give them props for spotting things in your code!
TL;DR
Put yourself in your reviewer’s shoes, and think of what you can add to help make the review process smoother with less work to do, which should result in getting your code out faster~! ✌️
