Back to Details

pr-stacking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Stacking

PR堆叠

Break large features into logical, dependent PRs for better code quality and easier reviews.
将大型功能拆分为逻辑化的依赖型PR，以提升代码质量并简化评审流程。

Prerequisites

前置条件

bash
undefined
bash
undefined

Install GitHub CLI (required for PR creation)

安装GitHub CLI（创建PR必需）

brew install gh # macOS
brew install gh # macOS

or: sudo apt install gh # Ubuntu/Debian

或：sudo apt install gh # Ubuntu/Debian

Authenticate

认证

gh auth login
undefined
gh auth login
undefined

When to Stack

何时使用堆叠

Stack PRs when:
  • Feature spans multiple logical steps (frontend + backend, model + UI)
  • Change exceeds ~300 lines of diff
  • Work can be merged incrementally
Skip stacking for:
  • Single-purpose bug fixes
  • Small, isolated changes
  • Refactoring within one file
在以下场景使用PR堆叠：
  • 功能包含多个逻辑步骤（前端 + 后端、模型 + UI）
  • 变更的差异超过约300行
  • 工作可以增量合并
以下场景无需堆叠：
  • 单一用途的Bug修复
  • 小型、独立的变更
  • 单个文件内的重构

Quick Start

快速开始

bash
undefined
bash
undefined

1. Create first PR branch from main

1. 从main分支创建首个PR分支

git checkout main && git pull git checkout -b feat/user-api
git checkout main && git pull git checkout -b feat/user-api

2. Make changes, commit, push

2. 进行变更、提交、推送

git add . && git commit -m "Add user API endpoint" git push -u origin feat/user-api
git add . && git commit -m "Add user API endpoint" git push -u origin feat/user-api

3. Stack: create dependent branch FROM current branch

3. 堆叠：从当前分支创建依赖分支

git checkout -b feat/user-ui # branches from feat/user-api
git checkout -b feat/user-ui # 基于feat/user-api分支创建

4. Continue working on dependent changes

4. 继续处理依赖变更

git add . && git commit -m "Add user profile component" git push -u origin feat/user-ui
undefined
git add . && git commit -m "Add user profile component" git push -u origin feat/user-ui
undefined

Core Workflow

核心工作流

Branch Naming

分支命名

feat/<feature>-1-<step>   # First in stack
feat/<feature>-2-<step>   # Second in stack
feat/<feature>-3-<step>   # Third in stack
Example:
feat/dark-mode-1-theme-context
feat/dark-mode-2-toggle-component
feat/dark-mode-3-persist-preference
feat/<feature>-1-<step>   # 堆叠中的第一个分支
feat/<feature>-2-<step>   # 堆叠中的第二个分支
feat/<feature>-3-<step>   # 堆叠中的第三个分支
示例：
feat/dark-mode-1-theme-context
feat/dark-mode-2-toggle-component
feat/dark-mode-3-persist-preference

PR Descriptions

PR描述

Include stack context in PR body:
markdown
undefined
在PR正文中包含堆叠上下文：
markdown
undefined

Stack Context

堆叠上下文

  • Depends on: #123 (theme context)
  • Followed by: #125 (persist preference)
  • 依赖于: #123 (theme context)
  • 后续分支: #125 (persist preference)

This PR

本次PR内容

Adds toggle component for switching themes.
undefined
添加用于切换主题的toggle组件。
undefined

Merge Order

合并顺序

Merge from bottom to top:
  1. Merge base PR first (#123 theme context)
  2. Rebase dependent PR onto updated main
  3. Merge next PR (#124 toggle component)
  4. Repeat until stack is fully merged
从下往上合并：
  1. 首先合并基础PR（#123 theme context）
  2. 将依赖PR变基到更新后的main分支
  3. 合并下一个PR（#124 toggle component）
  4. 重复此过程直到所有堆叠分支合并完成

Rebasing Stacked Branches

变基堆叠分支

When base PR changes:
bash
undefined
当基础PR发生变更时：
bash
undefined

Update base branch

更新基础分支

git checkout feat/dark-mode-1-theme-context git pull origin feat/dark-mode-1-theme-context
git checkout feat/dark-mode-1-theme-context git pull origin feat/dark-mode-1-theme-context

Rebase dependent branch

变基依赖分支

git checkout feat/dark-mode-2-toggle-component git rebase feat/dark-mode-1-theme-context
git checkout feat/dark-mode-2-toggle-component git rebase feat/dark-mode-1-theme-context

Force push (branch only, never main)

强制推送（仅针对分支，切勿用于main分支）

git push --force-with-lease
undefined
git push --force-with-lease
undefined

References

参考资料

  • references/workflow-steps.md - Detailed step-by-step guide
  • references/rebase-guide.md - Handling conflicts and rebasing
  • references/workflow-steps.md - 详细的分步指南
  • references/rebase-guide.md - 冲突处理与变基指南