stacked-prs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stacked PRs

堆叠式PR

Break large features into small, reviewable PRs that depend on each other. Merge in order for clean history.

将大型功能拆分为相互依赖的小型、便于评审的PR。按顺序合并以保持清晰的提交历史。

Quick Reference

快速参考

main ──────────────────────────────────────────●
                                              /
PR #3 (final)  ─────────────────────────●────┘   ← Merge last
                                       /
PR #2 (middle) ────────────────────●──┘          ← Depends on #1
                                  /
PR #1 (base)   ────────────────●──                ← Merge first
                              /
feature/auth ──────●────●────●                    ← Development

main ──────────────────────────────────────────●
                                              /
PR #3 (最终)  ─────────────────────────●────┘   ← 最后合并
                                       /
PR #2 (中间) ────────────────────●──┘          ← 依赖于#1
                                  /
PR #1 (基础)   ────────────────●──                ← 首先合并
                              /
feature/auth ──────●────●────●                    ← 开发分支

Workflow

工作流程

1. Plan the Stack

1. 规划堆叠结构

bash

undefined

bash

undefined

Identify logical chunks

确定逻辑拆分模块

Example: Auth feature

示例：认证功能

PR 1: Add User model + migrations

PR 1: 添加User模型 + 数据库迁移

PR 2: Add auth service + tests

PR 2: 添加认证服务 + 测试

PR 3: Add login UI + integration tests

PR 3: 添加登录UI + 集成测试

undefined

undefined

2. Create Base Branch

2. 创建基础分支

bash

git checkout main
git pull origin main
git checkout -b feature/auth-base

bash

git checkout main
git pull origin main
git checkout -b feature/auth-base

Implement first chunk

实现第一个模块

git add -p git commit -m "feat(#100): Add User model" git commit -m "feat(#100): Add user migrations"

Push and create first PR

推送并创建第一个PR

git push -u origin feature/auth-base gh pr create --base main --title "feat(#100): Add User model [1/3]"
--body "## Stack

PR 1/3: User model (this PR)
PR 2/3: Auth service (depends on this)
PR 3/3: Login UI (depends on #2)

git push -u origin feature/auth-base gh pr create --base main --title "feat(#100): Add User model [1/3]"
--body "## 堆叠结构

PR 1/3: 用户模型（当前PR）
PR 2/3: 认证服务（依赖当前PR）
PR 3/3: 登录UI（依赖#2）

Changes

变更内容

Add User model with validation
Add database migrations"

undefined

添加带验证的User模型
添加数据库迁移"

undefined

3. Stack Next PR

3. 堆叠下一个PR

bash

undefined

bash

undefined

Branch from first PR's branch (not main!)

从第一个PR的分支创建新分支（不要从main分支创建！）

git checkout -b feature/auth-service

Implement second chunk

实现第二个模块

git add -p git commit -m "feat(#100): Add auth service" git commit -m "test(#100): Add auth service tests"

Push and create PR targeting FIRST branch

推送并创建以第一个分支为基础的PR

git push -u origin feature/auth-service gh pr create --base feature/auth-base
--title "feat(#100): Add auth service [2/3]"
--body "## Stack

PR 1/3: User model (#101)
PR 2/3: Auth service (this PR)
PR 3/3: Login UI (depends on this)

Depends on #101 - merge that first"

undefined

git push -u origin feature/auth-service gh pr create --base feature/auth-base
--title "feat(#100): Add auth service [2/3]"
--body "## 堆叠结构

PR 1/3: 用户模型（#101）
PR 2/3: 认证服务（当前PR）
PR 3/3: 登录UI（依赖当前PR）

依赖于#101 - 请先合并该PR"

undefined

4. Continue Stacking

4. 继续堆叠后续PR

bash

git checkout -b feature/auth-ui

bash

git checkout -b feature/auth-ui

Implement third chunk

实现第三个模块

git commit -m "feat(#100): Add login form" git commit -m "test(#100): Add login integration tests"

git push -u origin feature/auth-ui gh pr create --base feature/auth-service
--title "feat(#100): Add login UI [3/3]"

---

git commit -m "feat(#100): Add login form" git commit -m "test(#100): Add login integration tests"

git push -u origin feature/auth-ui gh pr create --base feature/auth-service
--title "feat(#100): Add login UI [3/3]"

---

Managing the Stack

管理堆叠结构

When Base PR Gets Feedback

当基础PR收到评审反馈时

bash

undefined

bash

undefined

Make changes to base PR

对基础PR进行修改

git checkout feature/auth-base git add -p git commit -m "fix: Address review feedback" git push

Rebase dependent PRs

变基依赖的PR

git checkout feature/auth-service git rebase feature/auth-base git push --force-with-lease

git checkout feature/auth-ui git rebase feature/auth-service git push --force-with-lease

undefined

git checkout feature/auth-service git rebase feature/auth-base git push --force-with-lease

git checkout feature/auth-ui git rebase feature/auth-service git push --force-with-lease

undefined

When Base PR Merges

当基础PR合并后

bash

undefined

bash

undefined

After PR #1 merges to main

在PR #1合并到main分支后

git checkout main git pull origin main

Update PR #2 to target main now

更新PR #2的基础分支为main

gh pr edit 102 --base main

Rebase PR #2 on main

将PR #2变基到main分支

git checkout feature/auth-service git rebase main git push --force-with-lease

Repeat for PR #3 after #2 merges

在#2合并后，对PR #3重复上述操作

---

---

Stack Visualization

堆叠结构可视化

Track your stack with comments:

markdown

undefined

通过表格跟踪堆叠状态：

markdown

undefined

PR Stack for Auth Feature (#100)

认证功能PR堆叠（#100）

Order	PR	Status	Branch
1	#101	Merged	feature/auth-base
2	#102	Review	feature/auth-service
3	#103	Draft	feature/auth-ui

Merge order: #101 -> #102 -> #103

---

顺序	PR	状态	分支
1	#101	已合并	feature/auth-base
2	#102	评审中	feature/auth-service
3	#103	草稿	feature/auth-ui

合并顺序: #101 -> #102 -> #103

---

Automation Script

自动化脚本

bash

#!/bin/bash

bash

#!/bin/bash

stack-rebase.sh - Rebase entire stack after changes

stack-rebase.sh - 修改后重新变基整个堆叠结构

STACK=( "feature/auth-base" "feature/auth-service" "feature/auth-ui" )

BASE="main"

for branch in "${STACK[@]}"; do echo "Rebasing $branch onto $BASE..." git checkout "$branch" git rebase "$BASE" git push --force-with-lease BASE="$branch" done

echo "Stack rebased successfully!"

---

STACK=( "feature/auth-base" "feature/auth-service" "feature/auth-ui" )

BASE="main"

for branch in "${STACK[@]}"; do echo "Rebasing $branch onto $BASE..." git checkout "$branch" git rebase "$BASE" git push --force-with-lease BASE="$branch" done

echo "Stack rebased successfully!"

---

Tools for Stacked PRs

堆叠式PR工具

GitHub CLI Extensions

GitHub CLI扩展

bash

undefined

bash

undefined

Install stacked PR helper

安装堆叠PR辅助工具

gh extension install dlvhdr/gh-dash

View PR dependencies

查看PR依赖关系

gh pr view --json baseRefName,headRefName

undefined

gh pr view --json baseRefName,headRefName

undefined

Third-Party Tools

第三方工具

Graphite - graphite.dev (full stack management)
Stacked - stacked.dev
git-branchless - github.com/arxanas/git-branchless

Graphite - graphite.dev（完整堆叠管理工具）
Stacked - stacked.dev
git-branchless - github.com/arxanas/git-branchless

Best Practices

最佳实践

DO:
✅ Keep each PR < 400 lines
✅ Make each PR independently reviewable
✅ Document the stack in PR descriptions
✅ Number PRs clearly [1/3], [2/3], [3/3]
✅ Use draft PRs for incomplete stack items
✅ Rebase after feedback, don't merge

DON'T:
❌ Create circular dependencies
❌ Stack more than 4-5 PRs deep
❌ Leave stacks open for > 1 week
❌ Force push to already-approved PRs
❌ Merge out of order

建议做法：
✅ 每个PR代码量控制在400行以内
✅ 确保每个PR可独立评审
✅ 在PR描述中记录堆叠结构
✅ 清晰标记PR序号 [1/3], [2/3], [3/3]
✅ 对未完成的堆叠项使用草稿PR
✅ 收到反馈后执行变基，不要合并

不建议做法：
❌ 创建循环依赖
❌ 堆叠超过4-5个PR
❌ 堆叠结构保留超过1周
❌ 对已通过评审的PR执行强制推送
❌ 不按顺序合并

When NOT to Stack

不适合使用堆叠PR的场景

Small features (< 300 lines total)
Unrelated changes
Urgent hotfixes
Single-purpose refactors

小型功能（总代码量<300行）
不相关的变更
紧急修复
单一目的的重构

PR Template for Stacked PRs

堆叠式PR模板

markdown

undefined

markdown

undefined

Summary

摘要

Brief description of this PR's changes

当前PR变更内容的简要描述

Stack Position

堆叠位置

PR 1/N: Description (#xxx) - [Status]
PR 2/N: This PR
PR 3/N: Description (#xxx) - [Status]

PR 1/N: 描述内容 (#xxx) - [状态]
PR 2/N: 当前PR
PR 3/N: 描述内容 (#xxx) - [状态]

Dependencies

依赖关系

Depends on: #xxx (merge that first) Blocks: #xxx (must merge this first)

依赖于: #xxx（请先合并该PR）阻塞: #xxx（必须先合并当前PR）

Changes

变更内容

Change 1
Change 2

变更1
变更2

Test Plan

测试计划

Tests added
CI passes

undefined

添加测试
CI执行通过

undefined