Stacked Pull Requests
Stacked Pull Requests
Stacked pull requests are a workflow in which a larger piece of work is split into a linear series of small, reviewable branches. Each branch builds on the previous one — its Git parent is the branch before it in the stack — rather than all branches pointing directly at main.
main ← feature/part-1 ← feature/part-2 ← feature/part-3
Why Stack PRs Instead of One Big PR?
| Benefit | Description |
|---|---|
| Smaller cognitive load | Reviewers focus on one cohesive change at a time, which increases both review speed and quality. |
| Faster feedback loop | You can incorporate feedback from early layers while still making progress on later ones. |
| Reduced merge conflicts | Continuous merging and rebasing prevents a single, painful conflict resolution session at the end. |
| Clear dependency chain | Each PR documents why the next change is needed, creating a narrative that guides the reader through the work. |
| Safer deploys and easier rollbacks | A problematic layer can be reverted without losing unrelated progress in the rest of the stack. |
| Parallel collaboration | Teammates can review or QA early layers while you continue coding later ones. |
| Higher merge velocity | Small PRs tend to meet team size guidelines and pass CI faster than large ones. |
| Better blame granularity | Git history explains intent step by step, making future debugging faster. |
When to Use Stacked PRs
Stacking works well when a task is:
- A large refactor that touches many files across the codebase.
- A multi-step feature with a natural sequence (schema change, then backend logic, then API endpoint, then UI).
- A risky migration where you want to validate each stage before moving to the next.
- Exploratory work where earlier structural changes unlock later polish.
Avoid stacking when:
- The change is already small enough to review in one sitting.
- The dependencies between parts run in both directions — if part A needs part B and part B needs part A, isolate the responsibilities first.
- Your team or tooling cannot easily visualise the chain. Educate the team before introducing the workflow.
Core Principles
- Each PR must deliver one reviewable, internally coherent improvement. Keep the scope narrow.
- The diff should show only what is new relative to the previous layer. Rebase as needed to keep branches clean.
- Maintain a narrative flow: the description of each PR should reference the one before it and preview the one after.
- CI must stay green at every layer. No broken intermediate states.
- Do not sneak unrelated fixes into a later stack layer. If a fix is independent of the feature, create a separate PR off
main.
Branch Naming
Use a shared prefix so that your IDE, Git hosting platform, and teammates can sort and identify the stack at a glance. Number the branches to make the ordering obvious:
feature/payments/01-models
feature/payments/02-service
feature/payments/03-endpoints
feature/payments/04-ui
This convention also makes rebasing and updating the stack straightforward — you always know which branch comes next.