What a stacked pull request is
You have finished a large change.
It touches several parts of the codebase, the diff is long, and you already know that one giant pull request is hard to review.
Before you write any more code, you face a real decision: keep it as one pull request, or break it into a chain of stacked pull requests where each layer builds on the one below.
This guide helps you make that call before you start, then shows the maintenance obligations GitHub documents for stacks, so you know what you are signing up for either way.
GitHub describes stacked pull requests as a way to break large code changes into a chain of smaller, dependent pull requests that you can review and merge independently.
Each pull request in the stack has the branch below it as its base.
The bottom layer is the first thing reviewers see and the first thing that can merge; upper layers only make sense once the layers beneath them exist.
The word dependent matters.
Unlike splitting work into unrelated pull requests, a stack is a single change sliced vertically.
If the bottom layer changes, everything above it usually needs to be rebased.
When a stack fits your change
There is no universal rule that a large change must be stacked.
The decision depends on three questions you can answer before writing code.
- Does the change have independently reviewable layers? If you can describe each part in a sentence, such as a data model change, then an interface built on it, then a feature using that interface, a stack gives reviewers a smaller diff to reason about at each step. If every part only makes sense in the context of the whole, splitting may just create pull requests that reviewers cannot approve on their own.
- Can reviewers start on the bottom layer while upper layers are still in progress? A stack pays off when the bottom layer can be reviewed and merged while you keep building upward. If your reviewers will wait for the entire stack anyway, you have added structure without gaining earlier feedback.
- Can your team absorb the overhead of dependent branches? Stacks require ongoing rebase and restructuring work, which the next section describes. If your team rarely rebases and has no appetite for it, a single pull request, or a genuinely independent split, may be the more honest choice.
If most answers point toward a stack, the structure can help.
If they point away, forcing a stack will not make review easier; it will just move the difficulty into maintenance.