Back to Details

stacked-prs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stacked Pull Requests

堆叠式拉取请求（Stacked Pull Requests）

Overview

概述

Stacked PRs are dependent pull requests where each PR builds on the previous one. Use this pattern for complex features that need logical separation and parallel review.
堆叠式PR是相互依赖的拉取请求，每个PR都基于前一个PR构建。对于需要逻辑拆分和并行评审的复杂功能，可以采用这种模式。

When to Use

适用场景

✅ Use Stacked PRs When:

✅ 适合使用堆叠式PR的情况：

  • User explicitly requests "stacked PRs" or "dependent PRs"
  • Large feature needs to be split into logical phases
  • Each phase has clear dependencies on previous phases
  • User is comfortable with rebase workflows
  • 用户明确要求“堆叠式PR”或“依赖型PR”
  • 大型功能需要拆分为多个逻辑阶段
  • 每个阶段都明确依赖前一个阶段的成果
  • 用户熟悉变基（rebase）工作流

❌ Use Main-Based PRs When (Default):

❌ 适合使用基于主分支的PR的情况（默认）：

  • Features are independent
  • Simple bug fixes or enhancements
  • Multiple agents working in parallel
  • User doesn't specify preference
DEFAULT: Always prefer main-based PRs unless user explicitly requests stacking.
  • 功能相互独立
  • 简单的Bug修复或功能增强
  • 多个Agent并行工作
  • 用户未指定偏好
默认规则：除非用户明确要求堆叠，否则优先使用基于主分支的PR。

Branch Naming Convention

分支命名规范

Use sequential numbering to show dependencies:
bash
feature/001-base-authentication       # PR-001 (base)
feature/002-user-profile              # PR-002 (depends on 001)
feature/003-admin-panel               # PR-003 (depends on 002)
Alternative patterns:
bash
auth/01-foundation
auth/02-user-flow
auth/03-admin-features
使用连续编号来体现依赖关系：
bash
feature/001-base-authentication       # PR-001 (base)
feature/002-user-profile              # PR-002 (depends on 001)
feature/003-admin-panel               # PR-003 (depends on 002)
其他可选模式：
bash
auth/01-foundation
auth/02-user-flow
auth/03-admin-features

Creating Stacked PRs

创建堆叠式PR

Step 1: Create Base PR (PR-001)

步骤1：创建基础PR（PR-001）

bash
undefined
bash
undefined

Start from main

Start from main

git checkout main git pull origin main
git checkout main git pull origin main

Create base branch

Create base branch

git checkout -b feature/001-base-auth
git checkout -b feature/001-base-auth

Implement base functionality

Implement base functionality

... work ...

... work ...

Push and create PR

Push and create PR

git push -u origin feature/001-base-auth
git push -u origin feature/001-base-auth

Create PR in GitHub/GitLab

Create PR in GitHub/GitLab

Title: "[1/3] Base authentication foundation"

Title: "[1/3] Base authentication foundation"

Base: main

Base: main

Description: Include stack overview (see template below)

Description: Include stack overview (see template below)

undefined
undefined

Step 2: Create Dependent PR (PR-002)

步骤2：创建依赖PR（PR-002）

CRITICAL: Base on previous feature branch, NOT main
bash
undefined
关键注意事项：基于前一个功能分支创建，而非main分支
bash
undefined

Start from PR-001's branch

Start from PR-001's branch

git checkout feature/001-base-auth git pull origin feature/001-base-auth
git checkout feature/001-base-auth git pull origin feature/001-base-auth

Create dependent branch

Create dependent branch

git checkout -b feature/002-user-profile
git checkout -b feature/002-user-profile

Implement dependent functionality

Implement dependent functionality

... work ...

... work ...

Push and create PR

Push and create PR

git push -u origin feature/002-user-profile
git push -u origin feature/002-user-profile

Create PR in GitHub/GitLab

Create PR in GitHub/GitLab

Title: "[2/3] User profile management"

Title: "[2/3] User profile management"

Base: feature/001-base-auth ← NOT main!

Base: feature/001-base-auth ← NOT main!

Description: "Depends on PR #123"

Description: "Depends on PR #123"

undefined
undefined

Step 3: Create Final PR (PR-003)

步骤3：创建最终PR（PR-003）

bash
undefined
bash
undefined

Start from PR-002's branch

Start from PR-002's branch

git checkout feature/002-user-profile git pull origin feature/002-user-profile
git checkout feature/002-user-profile git pull origin feature/002-user-profile

Create final branch

Create final branch

git checkout -b feature/003-admin-panel
git checkout -b feature/003-admin-panel

Implement final functionality

Implement final functionality

... work ...

... work ...

Push and create PR

Push and create PR

git push -u origin feature/003-admin-panel
git push -u origin feature/003-admin-panel

Create PR in GitHub/GitLab

Create PR in GitHub/GitLab

Title: "[3/3] Admin panel with full auth"

Title: "[3/3] Admin panel with full auth"

Base: feature/002-user-profile ← NOT main!

Base: feature/002-user-profile ← NOT main!

Description: "Depends on PR #124"

Description: "Depends on PR #124"

undefined
undefined

PR Description Template

PR描述模板

Use this template for stacked PRs:
markdown
undefined
为堆叠式PR使用以下模板：
markdown
undefined

This PR

This PR

[Brief description of changes in THIS PR only]
[Brief description of changes in THIS PR only]

Depends On

Depends On

  • PR #123 (feature/001-base-auth) - Must merge first
  • Builds on top of authentication foundation
  • PR #123 (feature/001-base-auth) - Must merge first
  • Builds on top of authentication foundation

Stack Overview

Stack Overview

  1. PR #123: Base authentication (feature/001-base-auth) ← MERGE FIRST
  2. PR #124: User profile (feature/002-user-profile) ← THIS PR
  3. PR #125: Admin panel (feature/003-admin-panel) - Coming next
  1. PR #123: Base authentication (feature/001-base-auth) ← MERGE FIRST
  2. PR #124: User profile (feature/002-user-profile) ← THIS PR
  3. PR #125: Admin panel (feature/003-admin-panel) - Coming next

Review Guidance

Review Guidance

To see ONLY this PR's changes:
bash
git diff feature/001-base-auth...feature/002-user-profile
Or on GitHub: Compare 
feature/002-user-profile...feature/001-base-auth
(three dots)
To see ONLY this PR's changes:
bash
git diff feature/001-base-auth...feature/002-user-profile
Or on GitHub: Compare 
feature/002-user-profile...feature/001-base-auth
(three dots)

Testing

Testing

  • Tested in combination with PR #123
  • Includes tests for user profile functionality
  • Integration tests pass with base auth layer
undefined
  • Tested in combination with PR #123
  • Includes tests for user profile functionality
  • Integration tests pass with base auth layer
undefined

Managing Rebase Chains

管理变基链

When Base PR Changes (Review Feedback)

当基础PR发生变更（评审反馈）

If PR-001 gets updated, rebase dependent PRs:
bash
undefined
如果PR-001被更新，需要对依赖PR进行变基：
bash
undefined

Update PR-001 (base)

Update PR-001 (base)

git checkout feature/001-base-auth git pull origin feature/001-base-auth
git checkout feature/001-base-auth git pull origin feature/001-base-auth

Rebase PR-002 on updated base

Rebase PR-002 on updated base

git checkout feature/002-user-profile git rebase feature/001-base-auth git push --force-with-lease origin feature/002-user-profile
git checkout feature/002-user-profile git rebase feature/001-base-auth git push --force-with-lease origin feature/002-user-profile

Rebase PR-003 on updated PR-002

Rebase PR-003 on updated PR-002

git checkout feature/003-admin-panel git rebase feature/002-user-profile git push --force-with-lease origin feature/003-admin-panel

**IMPORTANT: Use `--force-with-lease` not `--force` for safety**
git checkout feature/003-admin-panel git rebase feature/002-user-profile git push --force-with-lease origin feature/003-admin-panel

**重要提示：为了安全，请使用`--force-with-lease`而非`--force`**

Merge Strategy

合并策略

Option A: Sequential Merging (Recommended)
  1. Merge PR-001 to main
  2. Change PR-002's base to main (GitHub: "Edit" button on PR)
  3. Merge PR-002 to main
  4. Change PR-003's base to main
  5. Merge PR-003 to main
Option B: Keep Stack Until End
  1. Merge PR-001 to main
  2. Keep PR-002 based on feature/001 until PR-001 fully merged
  3. Then rebase PR-002 onto main
  4. Repeat for PR-003
选项A：顺序合并（推荐）
  1. 将PR-001合并到main分支
  2. 将PR-002的目标分支改为main（GitHub：PR页面的“编辑”按钮）
  3. 将PR-002合并到main分支
  4. 将PR-003的目标分支改为main
  5. 将PR-003合并到main分支
选项B：保持堆叠直到全部完成
  1. 将PR-001合并到main分支
  2. 保持PR-002基于feature/001分支，直到PR-001完全合并
  3. 然后将PR-002变基到main分支
  4. 对PR-003重复上述步骤

Common Pitfalls

常见误区

❌ WRONG: All PRs from main

❌ 错误做法：所有PR都基于main分支创建

bash
git checkout main
git checkout -b feature/001-base
bash
git checkout main
git checkout -b feature/001-base

PR: feature/001-base → main

PR: feature/001-base → main

git checkout main # ← WRONG git checkout -b feature/002-next
git checkout main # ← 错误 git checkout -b feature/002-next

PR: feature/002-next → main # ← WRONG (independent, not stacked)

PR: feature/002-next → main # ← 错误（独立分支，非堆叠）

undefined
undefined

✅ CORRECT: Each PR from previous

✅ 正确做法：每个PR都基于前一个分支创建

bash
git checkout main
git checkout -b feature/001-base
bash
git checkout main
git checkout -b feature/001-base

PR: feature/001-base → main

PR: feature/001-base → main

git checkout feature/001-base # ← CORRECT git checkout -b feature/002-next
git checkout feature/001-base # ← 正确 git checkout -b feature/002-next

PR: feature/002-next → feature/001-base # ← CORRECT (stacked)

PR: feature/002-next → feature/001-base # ← 正确（堆叠式）

undefined
undefined

Agent Instructions

Agent指令

When delegating stacked PR creation to version-control agent:
Task: Create stacked PR branch structure

Stack Sequence:
1. PR-001: feature/001-base-auth → main (base layer)
2. PR-002: feature/002-user-profile → feature/001-base-auth (depends on 001)
3. PR-003: feature/003-admin-panel → feature/002-user-profile (depends on 002)

Requirements:
- Each branch MUST be based on previous feature branch
- Use sequential numbering (001, 002, 003)
- Include "depends on" notes in commit messages
- Create PR description with stack overview

CRITICAL: PR-002 bases on feature/001-base-auth, NOT on main
CRITICAL: PR-003 bases on feature/002-user-profile, NOT on main
当委托版本控制Agent创建堆叠式PR时：
Task: Create stacked PR branch structure

Stack Sequence:
1. PR-001: feature/001-base-auth → main (base layer)
2. PR-002: feature/002-user-profile → feature/001-base-auth (depends on 001)
3. PR-003: feature/003-admin-panel → feature/002-user-profile (depends on 002)

Requirements:
- Each branch MUST be based on previous feature branch
- Use sequential numbering (001, 002, 003)
- Include "depends on" notes in commit messages
- Create PR description with stack overview

CRITICAL: PR-002 bases on feature/001-base-auth, NOT on main
CRITICAL: PR-003 bases on feature/002-user-profile, NOT on main

Verification Checklist

验证检查清单

Before creating stacked PRs:
  • User explicitly requested stacked PRs
  • Feature has clear logical phases
  • Each phase has dependency on previous
  • User understands rebase workflow
  • Branch names use sequential numbering
  • Each branch created from correct base (previous feature branch)
  • PR descriptions include dependency information
  • Stack overview documented in each PR
创建堆叠式PR前需确认：
  • 用户明确要求使用堆叠式PR
  • 功能可拆分为清晰的逻辑阶段
  • 每个阶段都依赖前一个阶段
  • 用户理解变基工作流
  • 分支名称使用连续编号
  • 每个分支都基于正确的基础分支（前一个功能分支）创建
  • PR描述中包含依赖信息
  • 每个PR中都记录了堆叠概述

Related Skills

相关技能

  • git-worktrees
    - Work on multiple PRs simultaneously
  • git-workflow
    - General git branching patterns
  • code-review
    - Review strategies for stacked PRs
  • git-worktrees
    - 同时处理多个PR
  • git-workflow
    - 通用Git分支模式
  • code-review
    - 堆叠式PR的评审策略