Small PRs

When working with a team of developers, big or small, it's really valuable to keep your PRs as small as possible. There are plenty of good reasons for this:

• ⏩ Faster merges
• 🧑‍💻 More coding, less waiting
• 👍 Better quality reviews
• 🐛 Easier to fix or revert

Faster Merges

When you have a small PR, it's much quicker for someone to review, so it's faster for them to approve as well. That means you can merge your code more quickly. And that in turn lets you avoid issues such as frequently getting out of date with the base branch, fixing merge conflicts, etc.

It's also great because it means you can ship your code sooner; what's the point in writing code to leave it sitting in a branch for ages? Get it merged and get people using it!

More Coding, Less Waiting

Related to the speed of merging, if you split your work into separate PRs, then you can parallelise your work, saving a lot of waiting time. While your first PR is being reviewed, you can be working on writing more code that goes into your next PR. If you save it all up for one big merge, then you're sitting around waiting for a review - which takes longer because the PR is bigger!

For example, say you're working on reworking an existing feature. You might have a few things to change: text changes in the UI, renaming some variables and methods, and adding some extra functionality. You can easily do them as one big PR, but if you split them out into three distinct things, you can be working on adding your new functionality while the first two PRs get reviewed. And the reviews will happen more quickly because it's much easier to review and approve some copy changes and renaming than it is to review new functionality. And the review of the functionality is quicker because it’s clearer to see what’s changed, without the noise from copy changes and refactoring.

(I’m also a big fan of stacked PRs, which is a topic in itself.)

Better Quality Reviews

As a reviewer, when you have a smaller PR to review, it's much easier to get the full picture of what's changed. As mentioned above, when a PR is small and contains as few changes as possible, it’s harder for complexities to be hidden, and so it's easier to find and point out any issues. A smaller PR greatly reduces the risk of shipping bugs.

It's also just nicer, as a reviewer, to be able to spend less time reviewing PRs. Particularly if your team is so small that you're involved in reviewing most/all PRs, or if your team is so big that there are lots of PRs. I’ve been in both scenarios and you can spend a lot more of your day reviewing code rather than writing it. So the smaller the PR is, the better that is for the reviewer.

Easier To Fix Or Revert

If the worst happens and you ship a bug, having small PRs with atomic changes makes it much quicker and easier to identify and fix the bug. You can read the git commit history or PR history to find out what changed when - if you have lots of changes in one PR, it's easy for something to get overlooked.

It also means that if something significant went wrong and you need to back out of the change, you can just use git to revert that commit rather than having to manually change the code to how it was before.

PR Tips

So small PRs are great. And here are some other tips to make your PRs easier to review.

Review Your Own PR

Review your own PR. Seriously. It's amazing how much you can find to change just by looking back at the code in the PR view.

Keep Titles Concise

Make sure the PR title is easy to read. It should be a concise summary. It shouldn't be an explanation or a comment - leave that for the PR description. And if you find it hard to summarise, it might be a sign that your PR is doing too much - especially if you have the word "and" in there.

Make Descriptions Descriptive

Having kept the title short, you can then make full use of the PR description to explain what you've done. If you're changing UI, then Before and After screenshots are great, as are references to designs. If you've been unable to shrink it down and have had to create a particularly complex PR, then the description is a great place to try to make it less complex by summarising what's changed.

But Seriously, Review Your Own PRs

You can leave comments on your own PRs. They can really help to explain things to reviewers. Some good examples are "this is where the main change is", if the bulk of the PR is essentially wiring up that change. And "this was cut and pasted from here to here", if you've just moved code around - it really helps to make it easier to understand what's actually changed.

(Be careful only to leave comments on the PR when the comment is for the PR. If you're explaining how some non-obvious code works, for example, you might want to consider making that a comment in the code, so that it explains things to future readers of the code, rather than just the PR reviewer at that moment.)