“The PR is too large for reviewers to read,” “Other tasks stall while waiting on dependent changes,” “We cannot submit a PR until the entire feature is finished” — these are universal complaints heard across contract development and in-house support teams.
In April 2026, GitHub addressed this issue head-on by releasing its Stacked PRs feature in private preview (gihyo.jp / Hacker News). Following pioneering external tools like Graphite and Sapling, a platform-native standard has finally arrived.
In this article, we break down the core concept of Stacked PRs, their value in contract development, and common anti-patterns encountered in the field.
What are Stacked PRs?
Stacked PRs are a development workflow where a large feature change is chained into multiple smaller pull requests with defined dependencies.
PR #103 (UI): フォームコンポーネント追加
↑ depends on
PR #102 (API): エンドポイント実装
↑ depends on
PR #101 (DB): スキーマ追加
↑ depends on
mainEach PR is independently reviewable, and rebasing occurs automatically on upper layers as lower layers are merged. In GitHub's Stacked PRs, the PR view visualizes the entire stack, enabling click-through dependency navigation and bulk-merge operations.
Differences from existing tools
| Tool | Approach | Learning curve |
|---|---|---|
| Graphite CLI | Managed via dedicated CLI, GitHub integration | Medium (introduces proprietary concepts) |
| Sapling（Meta） | Git-compatible but distinct VCS | High (requires full team adoption) |
| jj (Jujutsu) | Git-compatible VCS, stacking is natural | High (requires understanding its design philosophy) |
| GitHub Stacked PRs | Native to GitHub, UI integration | Low (seamless for existing GitHub users) |
The greatest advantage of standardizing on GitHub is that the consensus-building cost for adoption is virtually zero. Getting formal approval to introduce new external tooling into a client's repository is often an uphill battle in contract work, making this a true breakthrough.
Structural reasons why massive PRs occur in contract development
Why do hard-to-review, gigantic PRs emerge in the first place? The causes generally boil down to three issues.
Cause 1: Packing interdependent changes into a single PR
Bundling database schema migrations, API implementations, and UI changes into a single PR easily results in 50+ modified files. The rule of “one PR per completed feature” is the primary driver of bloated pull requests.
Cause 2: Avoiding blocked work while waiting for reviews
When developers face the constraint that “the previous PR must be merged before opening the next,” they are incentivized to pack everything into one PR to avoid downtime. Stacked PRs eliminate this constraint.
Cause 3: Lack of review comprehension skills across the team
Without organizational training to thoroughly review large pull requests, passing changes with just a quick LGTM stamp becomes the norm, breeding technical debt. Keeping changes under 200 lines per PR with Stacked PRs dramatically lowers reviewer fatigue.
As discussed in our case study on Kauche's Automated AI Review and Merge Workflow, pairing AI reviews can help maintain baseline quality even on large PRs, but architecting PRs to prevent bloat from the start remains the ideal approach.
Implementation patterns that leverage Stacked PRs
Pattern 1: Vertical slicing
Pairing the classic technique of slicing features vertically with Stacked PRs yields tremendous results.
Stack 1: 「ユーザー登録機能（最小版）」
├ #201 DB: users テーブル
├ #202 API: POST /users
├ #203 UI: 登録フォーム
└ #204 E2E: 登録〜ログインまでの結合テストEach PR stays around 100 to 200 lines, enabling sequential merges every 1 to 2 days.
Pattern 2: Refactor stack
When refactoring alongside feature development, create a dedicated refactor stack on a separate branch lineage. This isolates the reviewer's cognitive load between functional changes and code restructuring.
Pattern 3: Migration stack
Structure legacy code migrations into four sequential PRs: Add new code → Run in parallel with legacy code → Switch traffic → Remove legacy code. This is a proven pattern for system modernization projects in contract work.
Large-scale migrations like those covered in Addressing Movable Type Vulnerabilities and CMS Migration demonstrate the true value of Stacked PRs.
Common implementation anti-patterns
Anti-pattern 1: Stacks that run too deep (5+ layers)
As stacks grow deeper, rebase failures cascade from lower layers. Keep stacks to three layers where possible, with a hard maximum of four. For extended feature work, break the stack into segments and merge incrementally.
Anti-pattern 2: Skip-merging in the middle of a stack
Merging higher-layer PRs while skipping middle ones introduces merge conflicts and corrupts Git history. Enforce a strict rule to always merge sequentially from the bottom up.
Anti-pattern 3: Large force-pushes within a stack
Frequent use of git push --force when updating lower PRs breaks branch relationships with upper layers. When updating lower layers, approach it prepared to rebuild the entire stack.
Anti-pattern 4: Inadequate explanations for reviewers
Failing to clearly state in the PR description that “PR #102 depends on #101” strips reviewers of essential context. Prepare a standard template that explicitly declares dependencies at the top of every PR.
Steps to integrate Stacked PRs into contract development
Step 1: Ensure the entire team understands “git rebase”
Stacked PRs are fundamentally built on a rebase strategy. For teams accustomed to merge, we recommend running a one-week rebase training exercise beforehand.
Step 2: Design CI pipelines to run per PR
Design CI workflows with dependency awareness so each layer's PR can pass tests independently. Ideally, your setup should resolve branch references and test upper layers even before lower layers are merged.
Step 3: Add stack information to PR templates
## このスタックの位置
- 親 PR: #101
- 子 PR: #103
- スタック全体: #100..#104
## このPRで完結する変更
- ...
## このPRが前提とする変更
- #101 の DB スキーマStep 4: Educate reviewers to read from the bottom up
The golden rule is to review stacks starting from the bottom layer. Reading from the top obscures underlying dependency context, leading to flawed code reviews.
Step 5: Measure average PR size during post-mortem retrospectives
The impact of Stacked PRs is reflected in your average lines changed per PR. Visualizing improvements after the first month—such as dropping from an average of 800 lines to 180 lines—accelerates team adoption.
Pairing this with AI tools to generate PR descriptions and extract dependencies, as outlined in our guide on Project Management Workflows with Claude Code, further reduces operational friction.
Summary — the skill of splitting PRs also transforms outsourcing quality
Stacked PRs are more than a convenient feature; they are a mechanism to embed the skill of decomposing changes into an engineering organization. In contract development, mastering this technique directly delivers three major outcomes:
- Faster review speeds → Shorter lead times → Faster client delivery
- Higher review quality → Less rework → Improved project profitability
- Smaller, incremental merges → Simpler rollbacks → Minimized blast radius during production incidents
At GleamHub, we provide onboarding support for modern Git workflows, including Stacked PRs, across contract development and in-house engineering teams. If your organization of 5 to 30 engineers is struggling with PR bottlenecks or chronic oversized PRs, we can assist starting with a two-week workflow audit and PR template overhaul.
