How to write a good pull request

Have you ever wondered why your pull requests (PRs) take ages to get reviewed? I am here to help!

1. Write smaller PRs

• Rather than having one massive PR with 1000 lines changed, having smaller PRs ensures it will be reviewed faster!
• This is because it’s way less intimidating and takes up a lot less time for someone else to review. It’s the considerate thing to do!

2. Easy PR descriptions

• PR descriptions can often be either too vague or too detailed.
• You want to strike a nice balance between the two so that a reviewer doesn’t have to wade through an essay or be left in the dark with no guidance.

PR Structure I like to personally follow:

• Context
  • One liner of any context that a reviewer may not be aware of just by looking at the code.
  • For example: “this is the design I am following” or “this is set up work for another PR”
• Problem
  • What problem does this PR solve?
    • For eg: If this is a bug, I like to outline the technical details of why the bug is happening here.
• Solution
  • I like to outline the high level technical flow of how my solution works here.
• Notes to reviewer
  • If there is something particularly gnarly or weird about my PR, I like to break it down a bit further here.
  • If there are things that a reviewer can ignore like “all the changes in this file is just formatting changes” then that also helps!
• Expected behaviour
  • List steps to reproduce the behaviour specified in the PR.
  • Actually outline the expected behaviour
    • If it’s a visual change, insert screenshots or gifs to display the expected behaviour actually occurring.

I don’t always follow this PR format to the T; I don’t always include all headings, or I may have different ones when needed. But this is my way of ensuring I have succinct, easy to read PR descriptions that reduce the cognitive overhead for a reviewer.

3. Offer to call and walk someone through a PR

• Particularly if its gnarly or touches old parts of the codebase and uses unfamiliar technologies.
• This encourages someone to review your PR, especially juniors, who may otherwise be scared to!

4. Self review

• Leaving a few comments on bits of your own PR can help you draw attention to specific parts of the code you really want thorough review on, or give quick explanations for your changes.

• For eg: "I did this because XYZ, but not sure if this is the correct pattern to follow"

• Going through this process should also help you catch any silly mistakes before a reviewer does

That’s all my advice, good luck getting your code reviewed faster!