Small PRs ship faster - QED

Introduction

Welcome to my very scientific paper where I propose that small PRs ship faster than big ones. I will construct my hypothesis with carefully crafted examples, concrete evidence and lots of words and sentences in general. I guarantee there will be no “cooking” involved. Once I’ve solidified my theory, I’ll wrap up my dissertation. Or, you’ll think of me the next time you’re thinking of writing a sending a big PR for review.

What’s a small PR?

When I say small PRs, I mean PRs that break work into very digestable chunks. Let’s imagine that you’re adding a new feature that spans several architecture layers of your backend. Perhaps you’ve got to code out several components (database persistence, business logic, API layer) and you’ve got to write several tests. You could ship those all as one change, or you could ship smaller PRs focused on each layer. Introduce new capabilities as one PR, then ship a subsequent PR that utilizes it. Along the way you might introduce new data types, dependencies, make external calls or perhaps new testing utilities to simplify test creation, those could be introduced separately too. So, by small, I mean breaking your code into logical chunks.

What I don’t mean by small PRs

I’m not advocating for aimlessly or arbitrarily splitting your code into meaningless chunks for the sake of it. That’s pointless and won’t yield the benefits. The intentionality and thought of how you slice things is really important. I’m also not talking about trivial one line changes (e.g. configuration change) or copy changes. They’re not the subject of our conversation.

The Benefits

Let’s jump right into the evidence… why should you even care about small PRs?

It’s faster… for everyone

Shall we start by illuminating the elephant in the room?

Small PRs typically incur the smallest footprint on the team as a whole. Small PRs will often have less communication overhead and discussion. With a smaller scope, and sharper focus, there’s a reduced need for comments and questions. You won’t expect 30+ comments on the PR. So… naturally team mates review your changes much faster. Any open conversations resolve faster. Even when there are changes, those can be tackled quickly. There’s also a greater motivation to make the changes since your footprint is much smaller. Small PRs increase the likelihood that you’re making changes while all the context is still fresh in your head — which increases change accuracy too! All meaning you’re getting your changes to prod faster.

It’s easier too…

When PRs are small there’s a profoundness in the simplicity it brings — small PRs reduce the cognitive load of the review process. When a PR is deliberately small, it’s really easy to review! It’s very easy to see the PR as a whole, it’s easy to evaluate what it does, how well it does. It’s also easy to spot unrelated changes or unintentional ones. When I’m reviewing a PR, I generally keep a mental list of behaviours in the code. Then I independently think of ways I’d test it before I look at the tests. A small change really supports deeper engagement in reviews. I can very quickly check whether the core behaviours are tested and whether we’ve covered edge cases. The same applies to other heuristics you’re using in your code reviews. For example, the sample principles applies to monitoring or observability gaps. Those gaps are way easier to identify in a small PR, than a much larger one. Small are PRs are simple and your colleagues will love it!

Safety first

Small PRs are much safer too! When we’ve logically sliced our PRs into smaller chunks, we’re going to prod with a smaller set of failure points. When your PR contains changes across several components, introduces new utilities, dependencies and more… you’re going to be in for a wild ride if something breaks. It’ll be much more difficult locating the needle-like failure hiding in your haystack of PR goodness. Smaller PRs are way better for rolling back and debugging. It’s easier to weigh in on whether our change broke something, or if it didn’t and we should look elsewhere. The smaller scope de-risks would-be-bigger-changes and helps us pinpoint failures faster!

The downsides

The professors wouldn’t accept my dissertation without some down sides. There are indeed some downsides to smaller PRs.

Smaller PRs can be disruptive. Small PRs means you're going faster and pushing things out quicker, which can result in more team disruptions. If you've right sized the PR it shouldn't take much time for the review — so the disruption should be small. You can also rotate reviews so you’re not prodding the same person every time.

It incurs some overhead for the author. You’re going to likely need some Git Fu to surgically chop your changes up consistently. You might need to have multiple branches built untop of each other. It can be a little cumbersome to make changes while you have branches stacked untop of each other. Git has gotten better at this though. There’s a relatively new feature called update-refs which allows you to make those changes without some of the pains. Here’s an article for that!

Any whoo… given I've articulated more benefits than cons... I can safely, scientifically and confidently say... QED!

For those of you wondering what this random “QED” thing is… it means “I’ve demonstrated what I’ve set out to demonstrate”.

Conclusion

Small PRs are pretty great... you should try them. They'll make you feel like you just transitioned from Waterfall to Agile if you've only done much bigger PRs. There are lots of great benefits to using them. I tried to restrain my passion into a smaller number of benefits. It’s faster, easier and safer and so much more!

I’d love to hear your thoughts on it!