Stack the Change,
Not the Risk

The Mega-PR Has a
Dependency Problem

A large pull request is rarely just a lot of code. It is usually several decisions arriving at the same checkpoint: a schema, a service boundary, an API, a user interface, tests, migration logic, and the compromises that connect them. The author sees one continuous story. The reviewer sees a wall of coupled uncertainty.

The familiar one-branch workflow offers two uncomfortable choices when those decisions depend on one another. Put the whole feature into one pull request and ask reviewers to hold the architecture in their heads at once. Or stop after each foundation, wait for it to merge, then begin the next layer. The first choice creates a review batch. The second creates an author queue.

That cost is not theoretical. Google’s 2018 study of modern code review combined 12 interviews, 44 survey responses, and logs for 9 million reviewed changes. It found code review was valued not only for catching problems, but also for maintaining standards, sharing knowledge, and improving design.[3] Microsoft researchers later analyzed roughly 1.5 million review comments across five projects and found that the proportion of feedback authors considered useful declined as the number of changed files rose.[4]

A controlled experiment with 50 mostly professional developers gives the small-change argument sharper edges. Mean review effectiveness was 59% for the small change and 35% for larger changes; review efficiency was also higher for the smaller condition.[5] That result supports focused review, but it does not prove stacked pull requests cause better production outcomes. The study used seeded defects, one subject system, and controlled review tasks—not a live team using GitHub’s new stack workflow.

The counterevidence matters just as much. A 2022 study examined 845,316 GitHub pull requests across 100 repositories, then compared the pattern with more than 400,000 Gerrit and Phabricator reviews. It found only a weak relationship between change size and time to merge.[6] A smaller diff can reduce the surface of a decision. It cannot create reviewer capacity, clarify ownership, accelerate a slow build, or make an unstable design suddenly coherent.

Google’s engineering guidance describes the target more usefully than a line-count limit: one self-contained conceptual change, with related tests and enough context for a reviewer to understand its consequences. The same guidance explicitly recommends stacking dependent changes when waiting would block the author, while keeping every intermediate state healthy.[7] The unit to optimize is not “small.” It is coherent, testable, and safe to land.

What a Stack
Actually Changes

GitHub defines a stack as two or more pull requests in the same repository arranged in one linear dependency chain. The bottom pull request targets the trunk, usually main. Every pull request above it targets the branch directly below. Each reviewer sees only the diff for that layer, while the stack map preserves the larger sequence.[1]

The important change is not the number of branches. It is that dependency moves from inside one large diff into the review model itself. A foundational correction belongs in the foundational branch. A UI comment belongs in the UI branch. Specialist reviewers can focus on the layers they understand best, and authors can keep building above work that has not merged yet.

GitHub’s native implementation, currently in public preview, goes beyond a manually chained set of ordinary pull requests. It treats the pull requests as a connected unit, displays their order, performs cascading rebases, and applies the trunk’s required reviews, CODEOWNERS, status checks, and relevant GitHub Actions workflows to every layer.[2] That closes several gaps that historically made stacks fragile: upper layers silently missing CI, branch bases drifting, and reviewers losing the map.

This model still demands architectural discipline. The lower a layer sits, the more upper work it can disturb. Stable contracts, additive migrations, compatibility boundaries, and feature flags belong low in the stack. Volatile presentation choices belong higher. If the foundation changes every afternoon, a tall stack simply gives instability more branches to travel through.

Smaller Is Not
Automatically Faster

The strongest case for stacked pull requests is not “more PRs equal more velocity.” It is that the workflow can preserve a small-batch review model even when the work is linearly dependent. DORA’s research treats small batches as a capability associated with software-delivery and organizational performance because they shorten feedback loops and make course correction less expensive.[9] That is evidence for a delivery principle, not proof that any particular stack tool improves outcomes.

A second controlled experiment, involving 28 developers, illustrates why the distinction matters. Decomposing a change reduced false-positive review findings and changed how reviewers navigated for context. It did not increase detected defects, improve understanding of the rationale, or reduce review time.[8] Smaller units helped reviewers reason differently, but the organizational queue remained an organizational queue.

The Metric Trap

One feature becoming four pull requests will make pull-request volume rise by definition. That is not productivity. Stack depth, lines changed, and PR count describe workflow shape. They do not tell leadership whether customers received value sooner or whether engineers spent the week resolving cascade conflicts.

Measure the feature across the whole chain: time to first meaningful review, active review time versus waiting time, review rounds, feature-level lead time, CI minutes, rebase conflicts, escaped defects, rollbacks, and reviewer confidence. The 2022 multi-platform study is a useful warning here: reducing change size alone did not meaningfully guarantee faster acceptance or merging.[6]

Where Stacks
Topple

Every layer adds a review object, a branch, a CI execution surface, and a place for the local and remote graph to diverge. GitHub automates much of that coordination, but automation does not make the cost disappear. It changes the cost from manual branch surgery into a workflow the team can observe and govern.

GitHub’s current constraints are concrete. Native stacks require every branch to live in the same repository and follow one linear history; cross-fork stacks and GitHub Desktop are not supported. Every layer must satisfy the trunk’s protection rules before it can merge. Auto-merge is not supported, although merge queues are. The feature is still in public preview and subject to change.[2][11]

Programmatic merging deserves special attention. GitHub’s rollout guidance says stacked merges require the asynchronous merge API; legacy pull-request merge endpoints cannot merge a stack. Organizations should update internal bots, dashboards, and ChatOps before expanding adoption.[12] A developer workflow is only healthy if the surrounding delivery system understands it.

Course correction should be ordinary, not embarrassing. Fold two layers when the boundary was artificial. Split off independent work. Merge the stable bottom and start a fresh stack. Return to one PR when the change is already coherent. The goal is not to defend the stack. The goal is to preserve review quality while moving useful software toward production.

A Stack You Can
Actually Ship

GitHub now maintains an official gh stack extension. The public-preview quickstart currently requires GitHub CLI 2.90.0 or later and Git 2.20 or later. Because preview requirements can change, confirm the current quickstart before standardizing a team image or developer container.[10]

gh auth login
gh extension install github/gh-stack

Build From the Bottom Up

git switch main
git pull --ff-only

# Bottom: stable model and contract
gh stack init --base main feat/auth-model
# Implement, test, stage, and commit the model.

# Middle: dependent API
gh stack add feat/auth-api
# Implement, test, stage, and commit the API.

# Top: dependent interface
gh stack add feat/auth-ui
# Implement, test, stage, and commit the UI.

gh stack view
gh stack submit --open

gh stack submit pushes the branches, creates or updates their pull requests, assigns the correct bases, and links the native stack. In an interactive terminal it opens an editor for titles, descriptions, and draft state. For a non-interactive draft flow, use gh stack submit --auto; add --open when the generated pull requests are ready for review.[10]

Put Feedback in the Layer That Owns It

gh stack checkout feat/auth-api
# Make the correction, test it, and commit it here.

gh stack rebase --upstack
gh stack push
gh stack top

The rebase command propagates the correction through every upper branch. The push command updates each active branch with explicit --force-with-lease protection. If conflicts occur, resolve and stage them, then run gh stack rebase --continue; use --abort to restore the pre-rebase state.[11]

gh stack view --short
gh stack sync
gh stack modify
gh stack merge
gh stack sync --prune

gh stack modify can fold, insert, reorder, rename, or drop layers, but it requires a clean working tree and linear history. gh stack merge merges an eligible bottom portion or the whole stack without bypassing protection rules. After merges, gh stack sync --prune fetches trunk, rebases remaining layers, pushes updates, syncs pull-request state, and removes merged local branches.[10]

Run a Real Pilot, Then Decide

GitHub recommends starting with a small group on real work, gathering feedback from both authors and reviewers, and auditing internal tooling before a broader rollout.[12] That is the right standard because direct empirical comparisons of GitHub’s new native stack workflow with ordinary GitHub pull requests remain limited. The supporting evidence is strongest for coherent decomposition and small-batch feedback; the platform feature is still new.