finishing-a-development-branch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Finishing a Development Branch

开发分支收尾流程

The Process

流程步骤

Step 1: Verify Tests

步骤1：验证测试用例

Determine test runner from project structure:

```
package.json
```
→
```
npm test
```
or
```
yarn test
```
```
Cargo.toml
```
→
```
cargo test
```
```
pyproject.toml
```
/
```
setup.py
```
→
```
pytest
```
```
go.mod
```
→
```
go test ./...
```
```
Makefile
```
with
```
test
```
target →
```
make test
```

Run tests. If any fail, report

⊘ BLOCKED:TESTS

with failure count and stop. Do not proceed to Step 2.

根据项目结构确定测试执行命令：

```
package.json
```
→
```
npm test
```
或
```
yarn test
```
```
Cargo.toml
```
→
```
cargo test
```
```
pyproject.toml
```
/
```
setup.py
```
→
```
pytest
```
```
go.mod
```
→
```
go test ./...
```
包含
```
test
```
目标的
```
Makefile
```
→
```
make test
```

执行测试。如果有测试用例失败，输出

⊘ BLOCKED:TESTS

并附带失败用例数量，终止流程，不要进入步骤2。

Step 2: Determine Base Branch

步骤2：确定目标基准分支

Find the branch this feature diverged from:

bash

undefined

查找当前特性分支的源分支：

bash

undefined

Check which branch has the closest merge-base

for candidate in main master develop; do if git rev-parse --verify "$candidate" >/dev/null 2>&1; then MERGE_BASE=$(git merge-base HEAD "$candidate" 2>/dev/null) if [ -n "$MERGE_BASE" ]; then echo "Candidate: $candidate (merge-base: $MERGE_BASE)" fi fi done


Select the candidate with the most recent merge-base (closest ancestor). If multiple branches share the same merge-base or detection is ambiguous, ask: "This branch could target `main` or `develop`. Which should it merge into?"

**Store the result** - subsequent steps reference `<base-branch>` meaning this determined value.


选择最近共同祖先（merge-base最新）的候选分支作为基准分支。如果多个分支的merge-base相同或检测结果不明确，询问用户："This branch could target `main` or `develop`. Which should it merge into?"

**存储判定结果** - 后续步骤中的`<base-branch>`指代此处判定的基准分支。

Step 3: Present Options

步骤3：提供操作选项

Present exactly these 4 options:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

严格展示以下4个选项：

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Step 4: Execute Choice

步骤4：执行用户选择的操作

Option 1: Merge Locally

选项1：本地合并

bash

git checkout <base-branch>
git pull
git merge <feature-branch>

If merge conflicts:

⊘ BLOCKED:CONFLICTS

Merge conflicts in:
- <conflicted files>

Cannot auto-resolve. User must:
1. Resolve conflicts manually
2. Run tests
3. Re-run this workflow

Stop. Do not proceed.

If merge succeeds:

bash

undefined

bash

git checkout <base-branch>
git pull
git merge <feature-branch>

如果出现合并冲突：

⊘ BLOCKED:CONFLICTS

Merge conflicts in:
- <conflicted files>

Cannot auto-resolve. User must:
1. Resolve conflicts manually
2. Run tests
3. Re-run this workflow

终止流程，不要继续执行。

如果合并成功：

bash

undefined

Verify tests on merged result

If tests pass, delete feature branch

git branch -d <feature-branch>


Then: Cleanup worktree (Step 5). Report `✓ MERGED`.

git branch -d <feature-branch>


然后执行：清理工作区（步骤5），输出`✓ MERGED`。

Option 2: Push and Create PR

选项2：推送并创建PR

Verify
gh
CLI is available:

bash

if ! command -v gh &>/dev/null; then
  echo "gh CLI not installed. Install from https://cli.github.com/ or push manually and create PR via web."
  exit 1
fi
gh auth status || echo "gh not authenticated. Run: gh auth login"

Extract title from first commit on branch (original intent):

bash

MERGE_BASE=$(git merge-base HEAD <base-branch>)
TITLE=$(git log --reverse --format=%s "$MERGE_BASE"..HEAD | head -1)
git push -u origin <feature-branch>
gh pr create --title "$TITLE" --body "$(cat <<'EOF'

验证
gh
CLI可用：

bash

if ! command -v gh &>/dev/null; then
  echo "gh CLI not installed. Install from https://cli.github.com/ or push manually and create PR via web."
  exit 1
fi
gh auth status || echo "gh not authenticated. Run: gh auth login"

从分支的第一条提交记录提取PR标题（对应原始开发需求）：

bash

MERGE_BASE=$(git merge-base HEAD <base-branch>)
TITLE=$(git log --reverse --format=%s "$MERGE_BASE"..HEAD | head -1)
git push -u origin <feature-branch>
gh pr create --title "$TITLE" --body "$(cat <<'EOF'

Summary

<2-3 bullets of what changed>

Test Plan

<verification steps> EOF )"


Report `✓ PR_CREATED` with PR URL. **Keep worktree intact** for continued work during review.

<verification steps> EOF )"


输出`✓ PR_CREATED`并附带PR链接，**保留工作区**以便评审期间继续修改。

Option 3: Keep As-Is

选项3：保留分支现状

Report

✓ PRESERVED

with branch name and worktree path.

Do not cleanup worktree.

输出

✓ PRESERVED

并附带分支名和工作区路径。

不要清理工作区。

Option 4: Discard

选项4：丢弃当前分支内容

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact confirmation. If not received, abort.

If confirmed:

bash

git checkout <base-branch>
git branch -D <feature-branch>

Then: Cleanup worktree (Step 5). Report

✓ DISCARDED

先二次确认：

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

等待用户输入精确的确认内容，如果未收到确认则终止操作。

如果确认丢弃：

bash

git checkout <base-branch>
git branch -D <feature-branch>

然后执行：清理工作区（步骤5），输出

✓ DISCARDED

。

Step 5: Cleanup Worktree

步骤5：清理工作区

For Options 1 and 4 only:

bash

undefined

仅适用于选项1和选项4：

bash

undefined

Check if currently in a worktree (not main repo)

if [ "$(git rev-parse --git-common-dir)" != "$(git rev-parse --git-dir)" ]; then

Get worktree root (handles invocation from subdirectory)

WORKTREE_ROOT=$(git rev-parse --show-toplevel) cd "$(git rev-parse --git-common-dir)/.." git worktree remove "$WORKTREE_ROOT" fi


**For Options 2 and 3:** Keep worktree intact.

if [ "$(git rev-parse --git-common-dir)" != "$(git rev-parse --git-dir)" ]; then

Get worktree root (handles invocation from subdirectory)

WORKTREE_ROOT=$(git rev-parse --show-toplevel) cd "$(git rev-parse --git-common-dir)/.." git worktree remove "$WORKTREE_ROOT" fi


**适用于选项2和选项3：** 保留工作区不变。

Quick Reference

快速参考

Option	Merge	Push	Keep Worktree	Cleanup Branch
1. Merge locally	✓	-	-	✓
2. Create PR	-	✓	✓	-
3. Keep as-is	-	-	✓	-
4. Discard	-	-	-	✓ (force)

选项	合并	推送	保留工作区	清理分支
1. 本地合并	✓	-	-	✓
2. 创建PR	-	✓	✓	-
3. 保留现状	-	-	✓	-
4. 丢弃内容	-	-	-	✓（强制删除）

Terminal States

终止状态

On completion, report exactly one:

State	Output	Meaning
`✓ MERGED`	Branch merged to `<base>` , worktree cleaned	Option 1 success
`✓ PR_CREATED`	PR #N at URL	Option 2 success
`✓ PRESERVED`	Branch kept at path	Option 3 success
`✓ DISCARDED`	Branch deleted, worktree cleaned	Option 4 success
`⊘ BLOCKED:TESTS`	N test failures	Cannot proceed
`⊘ BLOCKED:CONFLICTS`	Merge conflict in files	Cannot proceed

流程结束时严格输出以下其中一种状态：

状态	输出	含义
`✓ MERGED`	Branch merged to `<base>` , worktree cleaned	选项1执行成功
`✓ PR_CREATED`	PR #N at URL	选项2执行成功
`✓ PRESERVED`	Branch kept at path	选项3执行成功
`✓ DISCARDED`	Branch deleted, worktree cleaned	选项4执行成功
`⊘ BLOCKED:TESTS`	N test failures	流程无法继续
`⊘ BLOCKED:CONFLICTS`	Merge conflict in files	流程无法继续

Guardrails

防护规则

Blocking conditions (stop immediately):

Tests failing →
```
⊘ BLOCKED:TESTS
```
Merge conflicts →
```
⊘ BLOCKED:CONFLICTS
```

Mandatory confirmations:

Option 4 (Discard): Require typed "discard" confirmation

Cleanup rules:

Options 1, 4: Clean up worktree and branch
Options 2, 3: Preserve worktree

Never:

Proceed with failing tests
Merge without verifying tests on result
Delete work without typed confirmation
Force-push without explicit request

阻塞条件（立即终止流程）：

测试用例失败 →
```
⊘ BLOCKED:TESTS
```
合并冲突 →
```
⊘ BLOCKED:CONFLICTS
```

强制确认规则：

选项4（丢弃内容）：要求用户输入"discard"确认操作

清理规则：

选项1、4：清理工作区和特性分支
选项2、3：保留工作区

禁止操作：

测试失败时继续执行流程
未验证合并结果测试通过就完成合并
未收到输入确认就删除工作内容
无明确用户请求就执行强制推送

Integration

集成调用

Called by:

subagent-driven-development (Step 7) - After all tasks complete
executing-plans (Step 5) - After all batches complete

Pairs with:

using-git-worktrees - Cleans up worktree created by that skill

调用方：

subagent-driven-development（步骤7） - 所有任务完成后调用
executing-plans（步骤5） - 所有批次任务完成后调用

搭配使用：

using-git-worktrees - 清理该技能创建的工作区