Stacked Pull Requests
Stacked pull requests are a way of working in software development: a large change is broken down into several small proposals that build on each other and are reviewed one after another. This keeps each individual step manageable, even though the overall project is large.
Programmers almost never work alone on a piece of software. To make sure no one tinkers with the shared code unchecked, there’s a fixed procedure. Anyone who wants to make a change submits their proposed change, and colleagues look it over before it’s merged. Such a submitted proposal is called a pull request. With large-scale changes, however, a single proposal quickly becomes huge and practically unreadable. Stacked pull requests solve this: the large change is broken down into a chain of small proposals, each building on the previous one. The stack is reviewed and merged from the bottom up.
Why no one seriously reviews 3,000 changed lines
The quality of a code review declines as its size increases. With fifty changed lines, a colleague finds logical errors and asks follow-up questions. With three thousand lines, they skim through, nod, and write “looks good.” The review step still exists formally, but it no longer has any real effect. Studies at companies show fairly consistently that from around 400 changed lines onward, hardly any errors are still found.
The second advantage is time. Without a stack, a developer has to wait until their large proposal has been reviewed before they can keep building. Such waiting times often last a day or longer. With a stack, they simply put the next small proposal on top and keep working. The reviews run in parallel with further work.
One side effect is better traceability. Each step in the stack has its own title and its own rationale. If a bug turns up a year later, you can pinpoint the exact one small change that caused it. With a single giant proposal, all that’s left is the note “module rewritten.”
How the chain of branches comes about
Code is stored in version control systems, usually using the program Git. There’s a main state of the program, and alongside it branches, i.e., offshoots for experimenting. Normally you branch off from the main state and submit the result as a proposal. When stacking, you instead branch off from your own previous branch. This creates a chain: branch B builds on A, branch C on B.
Each branch is submitted as its own pull request. For each one, the reviewer only sees the difference from its predecessor, not the sum of all changes. Merging happens from the bottom: first A, then B, then C. This is also exactly where the main difficulty lies.
If a reviewer demands a correction in the bottommost branch, the ground shifts under all the branches above it. The chain has to be rebuilt, which Git calls “rebase.” With eight stacked branches, doing this by hand is tedious and error-prone. That’s why there are helper tools like Graphite, Sapling, or git-town that take care of the follow-up updates automatically.
From Meta and Google into small teams
The method grew big at Meta and Google. Both work with their own tools that support stacks from the ground up, and there the individual steps are usually called “diffs” rather than pull requests. From there, the working method spread via startups into the broader developer world.
On GitHub, the world’s largest platform for collaborative software development, stacking isn’t built in directly. It works there because when submitting a proposal, you can specify which branch it relates to. This gap is the reason there are now companies selling tools for stacking. On tech news sites, stacked pull requests therefore often show up in stories about developer tools and their funding rounds.
A common misconception: stacking doesn’t mean writing more code or typing faster. The amount of work stays the same; it’s just portioned differently. And the method isn’t mandatory. For a single three-line bug fix, a stack would simply be effort without benefit.