Getting your pull requests (PRs) reviewed and approved is critical to landing impact on your projects. A well-crafted PR can accelerate this process. The key is to make this as easy as possible for your reviewers.
Smaller is better
Have you ever opened someone else’s PR only to find it has dozens of changed files and a sea of green and red diffs? You probably dreaded going through it and moved on to review a different one. And with good reason, large PRs are a pain to review.
<sigh>
You can keep yours as small as possible in two ways:
Single-purpose: Limit your PRs to a single functional change. This could be a bug fix, a feature, or a refactoring. It’s very tempting to make multiple changes at once, or oftentimes multiple changes accumulate as you work, but this has several downsides. Multiple changes at once are riskier. If you need to undo or cherry-pick a commit, you’ll be dragging along unrelated changes. Most importantly for this discussion, it’ll be harder to review.
Keep it clean: Look at the diff and try to minimize it. Remove things like simple formatting changes, extra line breaks, and commented-out code (e.g. those print statements you used while debugging).
Give instructions
Your reviewer needs to do two things before approving your PR. The first is understanding your change, and the second is being confident that the changes are correct and safe. You can make this easier for them by adding a few elements to the PR description:
- An overview of the changes. What changed and why? It’s much easier to understand the code changes if you know what you are looking for and the intent. Without this, the reviewer needs to parse your intentions out of the diffs, which is harder.
- If applicable, suggest in what order to review the changed files. Sometimes a change in one place won’t make much sense until you see a change in a different file. E.g. if you see some error-checking code getting removed, you may think this is wrong and add a comment about it, only to later find that the same error checking is now happening elsewhere.
- Describe your testing. In addition to any automated CI, how did you test this code? Describe manual tests, paste commands, screenshots, and links to runs/results. This goes a long way to giving your reviewer confidence in your change.
- Choose your reviewers. This can depend on the team’s culture, but you can often get more traction if you assign the PR to one or two people. PRs that are unassigned or assigned to the whole team tend to receive less attention.
Be a good teammate
Last but not least, build some goodwill. This means reviewing other people’s PRs in a timely fashion, giving constructive comments, and being responsive to other people’s comments.
By following these practices, you’ll be leading by example and having a positive influence on your team, which is one of the elements of being a senior engineer.
What other practices do you follow for getting your pull requests approved faster?
Leave a Reply