Skip to main content

Stacked PR Workflow

Split a dependent feature into ordered pull requests that each show one reviewable layer.

Introduction​

A pull-request stack represents real dependencies between changes. The first branch targets main. Each later branch starts from and targets the branch below it.

The workflow improves review focus but adds branch maintenance whenever a lower layer changes.

Understanding the Workflow​

A stack layer is one branch and pull request in the chain. Its diff should contain one coherent increment relative to its direct base.

Definition

Stack Layer

One branch and pull request in an ordered dependency chain, containing the change introduced relative to its direct base.

A restack rebases dependent layers after their base changes. It proceeds from the changed layer upward because every higher layer depends on the result below it.

Definition

Restack

The ordered rebase of dependent branches after a lower branch or the target branch changes.

main
└── auth/schema       PR 1 -> main
    └── auth/service  PR 2 -> auth/schema
        └── auth/api  PR 3 -> auth/service

Every layer should leave its target branch buildable when merged. A pull request can depend on earlier layers while remaining understandable without later ones.

Applying It in Practice​

Choose boundaries based on contracts and dependencies. A schema change, service implementation, and API endpoint can form separate layers when each has its own tests and purpose.

Create branches from the layer below:

git switch main
git pull --ff-only
git switch -c auth/schema
# edit and commit

git switch -c auth/service
# edit and commit

git switch -c auth/api
# edit and commit

Open each pull request against its direct base:

auth/schema  -> main
auth/service -> auth/schema
auth/api     -> auth/service

When the root changes, restack in order:

git switch auth/service
git rebase auth/schema

git switch auth/api
git rebase auth/service

git push --force-with-lease origin auth/service auth/api

Review every updated diff after a restack. Conflict resolution can change behavior even when Git completes the rebase.

Merge from the root upward. After a lower layer lands, retarget or restack the next layer onto current main. Hosting platforms differ in how they update dependent pull requests, especially after squash merge or rebase-and-merge. Verify the displayed base and diff instead of assuming an automatic update.

Engineering Considerations​

Use a stack when layers have a clear dependency order and one combined pull request would be hard to review. Use parallel development when branches can merge in any order.

Keep stacks shallow enough for the team to maintain. Depth is less important than change frequency near the root. A stable four-layer stack can cost less than a two-layer stack whose base changes repeatedly.

Do not use line count as the only split rule. A small change with a difficult contract deserves its own review, while a larger mechanical change can remain one layer.

Stack-aware tools can automate restacking, branch submission, and pull-request retargeting. They do not resolve unclear dependencies or semantic conflicts.

Scaling and Operations​

Assign a stack owner who coordinates base changes and tells reviewers when force pushes alter a diff. Several developers can contribute, but one person should maintain the chain.

Run CI on each layer and on the combined stack where integration risk warrants it. A passing incremental diff does not prove that all layers work together.

Pause upper-layer review when a lower contract is undergoing redesign. Mechanical restacking onto an unstable foundation creates repeated work and misleading review comments.

Before each push, inspect the commits and diff relative to the intended base:

git log --oneline auth/schema..auth/service
git diff auth/schema...auth/service

Next Steps​