import DefinitionCard from "@site/src/components/DefinitionCard"

# 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.

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.

```text
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:

```bash
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:

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

When the root changes, restack in order:

```bash
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](./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:

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

## Next Steps

- [What are Stacked PRs?](/learn/concepts/git/stacked-prs): understand the branch and pull-request model
- [Parallel Development Workflow](./parallel-development): run independent work without a dependency chain
- [Human-in-the-Loop Review Workflow](./human-in-the-loop-review): review each layer and revision
- [Merge vs Rebase](/learn/concepts/git/merge-vs-rebase): choose safe integration and rewrite strategies