finishing-a-development-branch
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFinishing a Development Branch
完成开发分支
Overview
概述
Provide a structured, safe process for completing work on a development branch, including verification, merge strategy selection, and cleanup. This skill ensures no branch is merged without passing tests, and every destructive operation requires explicit user confirmation.
提供结构化、安全的流程来完成开发分支上的工作，包括验证、合并策略选择和清理。本技能确保没有分支可以在未通过测试的情况下合并，所有破坏性操作都需要用户明确确认。
When to Use
适用场景
- All planned work on a feature branch is complete
- A branch is ready for code review or merge
- Cleaning up after development work is finished
- Preparing a pull request for team review
- 功能分支上所有规划的工作已完成
- 分支已准备好进行代码评审或合并
- 开发工作完成后需要清理
- 准备拉取请求供团队评审
Phase 1: Verify All Tests Pass
阶段1：验证所有测试通过
[HARD-GATE] Do NOT proceed to any merge or PR activity without passing verification.
Before any merge or PR activity, invoke verification-before-completion to confirm:
- All tests pass (unit, integration, e2e as applicable)
- No lint errors or warnings
- Build succeeds
- No untracked files that should be committed
bash
undefined[HARD-GATE] 未通过验证的情况下禁止进行任何合并或PR相关操作。
在进行任何合并或PR操作前，调用 verification-before-completion 确认以下内容：
- 所有测试通过（单元测试、集成测试、端到端测试，如适用）
- 无lint错误或警告
- 构建成功
- 没有应该提交的未跟踪文件
bash
undefinedRun the project's full verification suite
运行项目完整的验证套件
Do NOT skip this step even if "tests were passing earlier"
即使「之前测试是通过的」也不要跳过这一步
If verification fails, STOP. Fix the failures before proceeding. Do NOT create PRs or merge branches with failing tests.
**STOP — Verification must pass before continuing to Phase 2.**
如果验证失败，立即停止。先修复问题再继续。禁止为测试失败的分支创建PR或合并分支。
**【停止】—— 进入第二阶段前必须通过验证。**Phase 2: Determine Base Branch
阶段2：确定基分支
Identify the branch to merge into, using this detection logic:
使用以下检测逻辑识别要合并到的目标分支：
Auto-Detection
自动检测
bash
undefinedbash
undefinedCheck for common base branch names
查找常见的基分支名称
git branch -a | grep -E 'remotes/origin/(main|master|develop)$'
git branch -a | grep -E 'remotes/origin/(main|master|develop)$'
Check what branch was the fork point
查找分支的分叉点
git log --oneline --decorate --graph HEAD...main --first-parent 2>/dev/null
git log --oneline --decorate --graph HEAD...master --first-parent 2>/dev/null
undefinedgit log --oneline --decorate --graph HEAD...main --first-parent 2>/dev/null
git log --oneline --decorate --graph HEAD...master --first-parent 2>/dev/null
undefinedBase Branch Selection Decision Table
基分支选择决策表
| Condition | Base Branch | Confidence |
|---|---|---|
| | High |
Only | | High |
| | Medium |
| Multiple candidates found | Ask user | Required |
| None of the above exist | Ask user | Required |
| 条件 | 基分支 | 置信度 |
|---|---|---|
存在 | | 高 |
仅存在 | | 高 |
存在 | | 中 |
| 找到多个候选分支 | 询问用户 | 必须 |
| 没有符合以上条件的分支 | 询问用户 | 必须 |
Verify Base Branch is Up to Date
验证基分支是最新版本
bash
git fetch origin
git log HEAD..<base-branch> --onelineIf the base branch has advanced since the feature branch was created, inform the user. They may want to rebase or merge base into the feature branch first.
bash
git fetch origin
git log HEAD..<base-branch> --oneline如果基分支在功能分支创建后有新的提交，告知用户。用户可能需要先执行rebase，或者将基分支合并到功能分支中。
Base Branch Divergence Decision Table
基分支分歧决策表
| Divergence | Action |
|---|---|
| Base has 0 new commits | Proceed normally |
| Base has 1-5 new commits | Inform user, suggest rebase |
| Base has 6+ new commits | Warn user, recommend merge or rebase before proceeding |
| Merge conflicts detected | STOP — resolve conflicts first |
STOP — Confirm the base branch with the user before proceeding.
| 分歧情况 | 操作 |
|---|---|
| 基分支无新提交 | 正常推进 |
| 基分支有1-5个新提交 | 告知用户，建议rebase |
| 基分支有6个以上新提交 | 警告用户，建议继续前先合并或rebase |
| 检测到合并冲突 | 【停止】—— 先解决冲突 |
【停止】—— 继续前必须和用户确认基分支。
Phase 3: Present Merge Options
阶段3：提供合并选项
Present exactly these four options to the user. Do NOT add or remove options.
How would you like to finish this branch?
A) Create PR -- push and open a pull request for review
B) Merge -- merge into <base> with a merge commit
C) Squash merge -- squash into one commit, merge into <base>
D) Leave as-is -- keep the branch, decide later仅向用户提供以下四个选项，禁止新增或删除选项。
你希望如何完成该分支的工作？
A) 创建PR -- 推送分支并打开拉取请求供评审
B) 合并 -- 生成合并commit，合并到<base>分支
C) 压缩合并 -- 压缩为单个commit，合并到<base>分支
D) 保持现状 -- 保留分支，后续再决定Option Selection Decision Table
选项选择决策表
| Context | Recommended Option | Why |
|---|---|---|
| Team project with code review | A) Create PR | Enables review workflow |
| Solo project, clean history | B) Merge | Preserves full branch history |
| Many WIP commits, messy history | C) Squash merge | Clean single commit on base |
| Work incomplete or uncertain | D) Leave as-is | No risk, decide later |
STOP — Wait for user to select an option. Do NOT assume a default.
| 场景 | 推荐选项 | 原因 |
|---|---|---|
| 有代码评审流程的团队项目 | A) 创建PR | 适配评审工作流 |
| 个人项目，需要保留清晰历史 | B) 合并 | 保留完整的分支提交历史 |
| 存在大量WIP commit，历史杂乱 | C) 压缩合并 | 基分支上仅保留单个清晰commit |
| 工作未完成或不确定 | D) 保持现状 | 无风险，后续再决定 |
【停止】—— 等待用户选择选项，禁止默认选择任意选项。
Phase 4: Execute Chosen Option
阶段4：执行选中的选项
Option A: Create Pull Request
选项A：创建拉取请求
bash
undefinedbash
undefinedPush the branch
推送分支
git push -u origin <branch-name>
git push -u origin <branch-name>
Generate PR title from branch name or recent commits
从分支名称或近期提交生成PR标题
Generate PR body from commit messages and diff summary
从提交信息和diff摘要生成PR内容
gh pr create --title "<title>" --body "<body>"
**PR Title Generation:**
- Derive from branch name: `feature/add-auth` becomes `Add authentication`
- Keep under 70 characters
- Use imperative mood
**PR Body Generation:**
- Summarize the changes (what and why)
- List key modifications
- Note any breaking changes
- Include test plangh pr create --title "<title>" --body "<body>"
**PR标题生成规则：**
- 从分支名称推导：`feature/add-auth` 对应 `Add authentication`
- 长度不超过70个字符
- 使用祈使语气
**PR内容生成规则：**
- 概述变更内容（是什么、为什么）
- 列出核心修改点
- 标注所有破坏性变更
- 包含测试方案Option B: Merge Locally
选项B：本地合并
bash
undefinedbash
undefinedSwitch to base branch
切换到基分支
git checkout <base-branch>
git checkout <base-branch>
Merge feature branch
合并功能分支
git merge <feature-branch>
git merge <feature-branch>
Delete the feature branch
删除功能分支
git branch -d <feature-branch>
**Confirmation required** before executing the merge.git branch -d <feature-branch>
执行合并前**需要用户确认**。Option C: Squash Merge
选项C：压缩合并
bash
undefinedbash
undefinedSwitch to base branch
切换到基分支
git checkout <base-branch>
git checkout <base-branch>
Squash merge
压缩合并
git merge --squash <feature-branch>
git merge --squash <feature-branch>
Commit with a comprehensive message
提交完整的commit信息
git commit -m "<squash commit message>"
git commit -m "<squash commit message>"
Delete the feature branch
删除功能分支
git branch -d <feature-branch>
**Squash commit message** should summarize all changes from the branch, not just the last commit.
**Confirmation required** before executing the squash merge.git branch -d <feature-branch>
**压缩合并的commit信息**应该概述分支的所有变更，而不仅仅是最后一次提交的内容。
执行压缩合并前**需要用户确认**。Option D: Leave Branch As-Is
选项D：保持分支现状
No action needed. Inform the user:
Branch <branch-name> left as-is.
You can return to it later with: git checkout <branch-name>无需操作，告知用户：
分支 <branch-name> 已保留。
你可以后续使用该命令切换回该分支：git checkout <branch-name>Phase 5: Cleanup
阶段5：清理
After executing options A, B, or C, perform cleanup:
执行选项A、B、C后，执行以下清理操作：
Remove Worktree (if applicable)
移除工作树（如适用）
If the branch was developed in a git worktree:
bash
undefined如果分支是在git worktree中开发的：
bash
undefinedNavigate out of the worktree first
先退出工作树目录
git worktree remove <worktree-path>
git worktree prune
undefinedgit worktree remove <worktree-path>
git worktree prune
undefinedClean Up Remote Tracking (Option B and C only)
清理远程跟踪（仅适用于选项B和C）
If the branch was previously pushed:
bash
undefined如果分支之前已经推送到远程：
bash
undefinedDelete remote branch after local merge
本地合并后删除远程分支
git push origin --delete <branch-name>
**Confirmation required** before deleting remote branches.git push origin --delete <branch-name>
删除远程分支前**需要用户确认**。Verify Final State
验证最终状态
bash
git status
git log --oneline -5Confirm the base branch is in the expected state.
bash
git status
git log --oneline -5确认基分支处于预期状态。
Confirmation Requirements
确认要求
[HARD-GATE] The following operations require explicit user confirmation before execution. Do NOT proceed on assumption. Always ask.
| Operation | Why Confirmation Is Required |
|---|---|
| Merge into base branch | Changes base branch history |
| Squash merge | Loses individual commit history |
| Delete local branch | Cannot be undone if not pushed |
| Delete remote branch | Affects other collaborators |
| Force remove worktree | May discard uncommitted changes |
| Rebase onto updated base | Rewrites commit history |
[HARD-GATE] 以下操作执行前必须获得用户明确确认，禁止假设执行，必须询问用户。
| 操作 | 需要确认的原因 |
|---|---|
| 合并到基分支 | 会修改基分支历史 |
| 压缩合并 | 会丢失独立的提交历史 |
| 删除本地分支 | 如果未推送无法恢复 |
| 删除远程分支 | 会影响其他协作者 |
| 强制移除工作树 | 可能丢弃未提交的变更 |
| Rebase到更新后的基分支 | 会重写提交历史 |
Anti-Patterns / Common Mistakes
反模式/常见错误
| Anti-Pattern | Why It Is Wrong | What to Do Instead |
|---|---|---|
| Merging without running tests | Broken code reaches base branch | Always run full verification first |
| Skipping base branch freshness check | Merge conflicts discovered late | |
| Auto-selecting merge strategy | User may prefer different approach | Always present all four options |
| Deleting branch without confirmation | Data loss risk | Ask before every deletion |
| Creating PR with failing CI | Wastes reviewer time | Fix CI before creating PR |
| Squash message from last commit only | Loses context of full branch work | Summarize all changes in squash msg |
| Leaving stale remote branches | Cluttered repository | Clean up remote after merge |
| Force-pushing after PR creation | Destroys review comments | Avoid force-push on PR branches |
| 反模式 | 错误原因 | 正确做法 |
|---|---|---|
| 未运行测试就合并 | 损坏的代码会进入基分支 | 始终先运行完整的验证流程 |
| 跳过基分支新鲜度检查 | 合并冲突发现过晚 | 执行 |
| 自动选择合并策略 | 用户可能偏好其他方案 | 始终提供全部四个选项 |
| 未确认就删除分支 | 存在数据丢失风险 | 每次删除前都询问用户 |
| 为CI失败的分支创建PR | 浪费评审者时间 | 创建PR前先修复CI问题 |
| 压缩合并的信息仅来自最后一次提交 | 丢失整个分支工作的上下文 | 压缩信息要概述所有变更 |
| 遗留过时的远程分支 | 仓库混乱 | 合并后清理远程分支 |
| PR创建后强制推送 | 会破坏已有的评审评论 | 避免在PR分支上强制推送 |
Error Handling
错误处理
| Error | Action |
|---|---|
| Merge conflicts | Report conflicts, ask user to resolve, do NOT auto-resolve |
| Push rejected | Fetch and check if rebase/merge is needed |
| PR creation fails | Check |
| Branch already deleted | Skip deletion, continue with remaining cleanup |
| Tests fail | STOP immediately, do NOT merge or create PR |
| Base branch does not exist on remote | Ask user to confirm the correct base |
| 错误 | 处理方式 |
|---|---|
| 合并冲突 | 上报冲突，要求用户解决，禁止自动解决 |
| 推送被拒绝 | 拉取最新代码，检查是否需要rebase/合并 |
| PR创建失败 | 检查 |
| 分支已被删除 | 跳过删除步骤，继续剩余清理流程 |
| 测试失败 | 立即停止，禁止合并或创建PR |
| 远程不存在该基分支 | 要求用户确认正确的基分支 |
Integration Points
集成点
| Skill | Integration |
|---|---|
| Must invoke in Phase 1 before any merge activity |
| Cleanup includes worktree removal if applicable |
| Squash commit message follows conventional commit format |
| PR creation (Option A) feeds into code review workflow |
| Branch completion is the final step of plan execution |
| Merge to main/release may trigger deployment pipeline |
| 技能 | 集成规则 |
|---|---|
| 第一阶段任何合并操作前必须调用 |
| 清理流程包含工作树移除（如适用） |
| 压缩合并的commit信息遵循约定式提交格式 |
| PR创建（选项A）会进入代码评审工作流 |
| 分支完成是规划执行的最终步骤 |
| 合并到main/发布分支可能触发部署流水线 |
Skill Type
技能类型
RIGID — Follow this process exactly. Every phase must be completed in order. Do NOT skip verification. Do NOT merge without user confirmation. Do NOT assume a merge strategy. Do NOT delete branches without asking.
RIGID（严格型） —— 必须严格遵循该流程，所有阶段必须按顺序完成。禁止跳过验证，禁止未获得用户确认就合并，禁止假设合并策略，禁止未询问就删除分支。