As a software engineer, I find myself creating large pull requests because it’s easy. Writing smaller pull requests takes practice. It also requires more of the boring planning part before I get to the fun part: writing code and enjoying the flow.
Even though I know how to write small pull requests, I’m tempted by large pull requests. I love 3-for-2 deals; I think I can be more efficient by bundling multiple changes together.
In reality, writing larger pull requests slows me down and makes me less efficient. Especially, when I’m working in a team. In this blog post, I explain why small pull requests are almost always better.
I’m tempted by large pull requests. I love 3-for-2 deals; I think I can be more efficient by bundling multiple changes together.
1. Small pull requests get faster code reviews
The most obvious benefit of small pull requests is that they are reviewed faster. Engineers tend to postpone — and often forget — code reviews when they see large pull requests.
Even when people start reviewing large pull requests quickly, it can easily take a lot of time to read them through. The longer it takes to review the pull request, the more likely it is that it won’t be done in one go. With large pull requests, reviewers often lose their focus and get pulled into other stuff.
2. Small pull requests get better code reviews
If you’ve reviewed large PRs, you’ve probably experienced code review fatigue. Keeping all the context of a large pull request in your head is very consuming — especially if the pull request includes multiple separate changes. The result is that the reviewer starts skimming code, leaves fewer comments, and ends up with a superficial “LGTM” review.
3. Small pull requests improve code quality
Have you ever looked at a large pull request, cringed, and thought: “This solution is not very good, but starting again from scratch would be too much work.” I certainly have — especially in cases where I’ve failed to help a less-experienced engineer understand the problem and solution properly.
Small pull requests speed up the feedback cycle. This ensures earlier discussion about the chosen solution and better design decisions. End result: higher quality code.
4. Small pull requests help protect your flow
Small pull requests help you protect your flow by making it easier to get back to the task at hand if something interrupts your work. And something always does.
To work in small pull requests, you need to learn how to split your work into smaller parts. For example, instead of working on a single huge “build feature” task, you should have a list of small, incremental tasks like “add database table”, “add feature gate”, etc.
Smaller tasks require you to keep less context in your mind. Less context makes it easier to get into flow. Suddenly, a thing that felt like a “mega-interruption” from your coworker becomes a small hindrance.
5. Small pull requests help you build features faster
Smaller pull requests help you stay motivated and keep momentum.
Splitting large entities of work into smaller subtasks is proven to make you move faster. Your work will feel more rewarding as you get a steady supply of small doses of dopamine every time you merge a pull request.
You’re also less likely to get stuck. Like when you have a big ball of mud in your hands and it's hard to know what you were doing and what do to next.
6. Small pull requests help your team build features faster
It’s common for a feature to be delayed for days — or even weeks — because someone who is on the critical path has a half-made, large pull request sitting in some WIP branch that they are not able to finish just yet. Maybe they’ve been pulled to another high-priority task, are helping with hiring, or simply got sick.
When you build in small pull requests, these kinds of blockers are less likely. Even when they happen, small pull requests are easier to hand over to other engineers in the team.
7. Small pull requests improve collaboration
When you split your work into smaller pull requests, you’ll also notice that it becomes easier to work on features together. Instead of a single engineer ploughing through a feature on their own for two weeks, you can have a few engineers do the same thing in less than a week.
Improved collaboration has multiple benefits including increased learning at work, higher job satisfaction, and higher quality solutions.
8. Small pull requests reduce risk
People often underestimate the complexity of the work they’re about to start. It is common for the scope of work to “unexpectedly” grow. As a result, you end up spending a lot more time on building unimportant things. Or, in the worst case, don’t ship anything, because you have more pressing priorities to handle.
At Swarmia, we plan every larger story together with the whole team and create an initial list of tasks that should all fit into a single pull request. More often than not we find our task list growing very large and realize that we have to cut scope (and our ambitions) if we want to ship the story in less than two weeks.
What makes a pull request “small”?
It would be tempting to define a “small” pull request solely based on how many lines it changes. However — as the points above also show — there are multiple things that can make a pull request complex.
Your focus should not be hitting a specific number of lines. Instead, focus on learning how to split your work into smaller increments so you can build small and focused pull requests.
Your focus should not be hitting a specific number of lines. Instead, focus on learning how to split your work into smaller increments so you can build small and focused pull requests.
Measuring the lines changed in pull requests is useful for understanding the overall trend in the way you work. Most changes you’re doing can be shipped in pull requests that have less than 200 lines changed.
Anything above 500 lines is definitely large. Often, these pull requests could have been shipped in smaller increments.
How can you create smaller pull requests?
Pre-plan your tasks. Before you start coding, take a moment to list all the separate steps required to complete the task.
Separate large refactorings from feature work. For example, if you need to touch a function that has 50 call sites, you can have a separate pull request for updating all the call sites and another one for your feature work.
Use feature flags. They allow you to merge code to master before the whole feature is ready. This makes building in small pull requests much easier — and improves internal testing and feature rollout as a bonus.
Don’t be afraid to create small pull requests. In the beginning, it may feel stupid to create a pull request for a task like “create database table for todo items.” Just do it.
Prioritize code review in your team. One of the biggest enemies of small pull requests is slow code review. If you have to wait for 2 days to get a review for a “create database table” pull request, creating these pull requests will feel unnecessary. To help, create a working agreement with the team where everyone agrees to review code in less than X hours.
If you can’t get your team to prioritize code review, find a single co-worker who will. Then, agree to work using small pull requests and prioritize reviewing each other’s code.
Use stacked pull requests. If you often have to wait for code reviews, stacking pull requests allows you to still continue on top of your previous work. Unfortunately, GitHub doesn't have great support for stacked pull requests. You’ll need additional tooling if you often stack more than two pull requests.
TL;DR
Small pull requests improve code reviews and code quality. They protect your flow and allow you to move faster. Small pull requests encourage feedback, improve collaboration, and reduce the risk of tasks ballooning and getting stuck.
Building in small, focused pull requests is a skill that requires practice. You’ll never get better if you never start. So start with the next task that you’re going to work on.
