Pull Request Tips and Customs
If you've read our other posts, then you know what to do when opening a pull request and what to look for when reviewing one. In this post, we will offer some tips and general customs to follow when working with pull requests.
Fast response times
Pull requests should not be open for a long time otherwise they will go stale. To help prevent this from happening, reviewers should start reviewing as soon as they possibly can. If any comments are left, then these should be answered and/or addressed quickly.
Keep it small
A small pull request will get looked at much quicker than a large one, because it is less overwhelming and isn't as scary looking. It is also easier to review and less prone to letting errors through.
As mentioned in Reviewing a Pull Request, keep the pull request on topic and don't include out of scope work. If you see a change is going to lead to a large pull request, consider splitting it up into multiple smaller pull requests.
Have a meeting
Sometimes a pull request can't be kept small, is very complex or creates great discussion between project members. If this is the case and it's possible, try to have a face-to-face meeting where you can discuss the pull request together and even make any necessary changes to the pull request.
It's often easier to come to agreements and explain complexities when you can talk to each other, rather than typing over comments. Just remember to keep the pull request up-to-date with any developments from the meeting.
Separate renames into their own pull request
Renaming classes, variables or functions can result in a big code change. If there is also a change to the functionality, it can be difficult to visualise the change amongst all the renaming. To solve this issue, you should instead do the renaming in its own branch, which will have its own pull request.
Be polite
Politeness will get you a long way in life. When leaving comments on a pull request, or responding to comments, talk in a respectable manner. If project members fail to do so, it can lead to conflicts between project members that can result in the deterioration of the project as a whole.
Suggestions over enforcement
Everyone has their own preferences. Unless there is a specific guideline enforced by the project standards, only offer suggestions. If there is a difference of opinion, raise this outside of the pull request. There is no need to hold up a pull request over personal preferences.
Give reasons and improvements
If you don't agree with a change, you should explain your reasons for this and offer suggestions for how you believe it could be improved. This will help the author to understand your concern and be able to address it better.
Request early review
Some projects may allow for authors to request a review of their change before they are fully complete. This can be useful if an author wants to ask for some feedback on the approach they have taken.
It's a good idea to add a work in progress tag at the start of your pull request title. Something such as "[WIP] - Title".
Show appreciation
A pull request isn't only for highlighting mistakes or bugs. Both authors and reviewers can show appreciation to each other. Appreciation can go a long way to making a person's day that much better.
Make it fun
Pull requests are boring, we all know it! But you can add bits of fun here and there. Make use of emojis and GIFs to add a bit of cheer to your comments.
Review others pull requests
Don’t only open pull requests. Review other projects members pull requests too. You don’t need to maintain a 1:1 ratio of opened to reviewed pull requests, but it's only fair that if other project members are spending time on your pull requests, you do the same back.
So there are some general customs you can follow when both authoring and reviewing pull requests. Hopefully you find them helpful.