github-pr-merge

GitHub PR 合并

验证合并前检查清单并处理合并后清理工作，然后合并拉取请求。

当前 PR

!gh pr view --json number,title,state -q '"PR #\(.number): \(.title) (\(.state))"' 2>/dev/null

核心工作流

1. 检查评论状态

确认所有评审评论至少有一条回复：

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
PR=$(gh pr view --json number -q '.number')

# Find unreplied comment IDs
gh api repos/$REPO/pulls/$PR/comments --jq '
  [.[] | select(.in_reply_to_id) | .in_reply_to_id] as $replied |
  [.[] | select(.in_reply_to_id == null) | select(.id | IN($replied[]) | not) | .id]
'

如果存在未回复的评论：

• 停止合并流程
• 通知用户：“发现未回复的评论：[IDs]。请先运行 github-pr-review。”
• 绝不要通过此技能回复评论

2. 检查里程碑

gh pr view $PR --json milestone -q '.milestone.title // "none"'

• 如果已分配里程碑：将其列入检查清单摘要（步骤 5）
• 如果没有里程碑：检查是否存在未完成的里程碑，并提醒用户

gh api repos/$REPO/milestones --jq '[.[] | select(.state=="open")] | length'

如果存在未完成的里程碑，但此 PR 没有关联里程碑，请在检查清单中显示警告： - Milestone: ⚠ not assigned (open milestones exist)

缺少里程碑不会阻止合并。这仅是一项警告。

3. 运行验证

运行测试、代码检查并验证 CI 检查。继续操作前，所有检查必须通过。

gh pr checks $PR

4. 验证变更日志是否完整

如果仓库没有 CHANGELOG.md，则跳过。否则，确保本次合并将发布的每个提交都已记录在变更日志中，这样发布晋级合并（develop → main）就不会遗漏提交记录。

列出此 PR 将合入基分支的提交，以及它新增的变更日志条目：

BASE=$(gh pr view $PR --json baseRefName -q .baseRefName)
HEAD=$(gh pr view $PR --json headRefName -q .headRefName)
git log --oneline origin/$BASE..origin/$HEAD
git diff origin/$BASE...origin/$HEAD -- CHANGELOG.md

• 每个会改变已发布行为的提交（feat/fix/perf，以及会影响行为的 refactor）必须有对应的变更日志条目；不会改变已发布行为的纯 chore/docs/test 提交可以省略。
• 对于发布晋级合并，还要确认版本号已更新（顶部的 ## [x.y.z] 条目是新增的），且与清单中的版本号一致。
• **如果任何会改变行为的提交未记录在变更日志中：停止。**报告未记录的提交，并请用户在合并前更新变更日志和版本号。绝不要通过此技能编辑变更日志。

5. 请用户确认

始终展示检查清单摘要，并在合并前征求用户确认：

Pre-merge checklist:
- Comments: all replied
- Tests: passing
- Lint: passing
- CI: green
- Milestone: v0.1.0 (or ⚠ not assigned)
- Changelog: complete (or n/a)

Ready to merge PR #X. Proceed?

6. 执行合并

先确定合并方向。这决定是否可以删除头分支：

gh pr view $PR --json baseRefName,headRefName -q '"\(.headRefName) -> \(.baseRefName)"'

分支删除规则：

• 主题分支 → develop（头分支是 feature/fix/等分支）：该分支已完成使命。建议删除它，并使用 --delete-branch 合并。
• develop → main（或任何以长期分支为头分支的合并）：绝不要删除头分支。develop 和 main 是永久分支。省略 --delete-branch，也不要建议删除。

# Add --delete-branch ONLY for a topic branch merging into develop.
gh pr merge $PR --merge --delete-branch --body "$(cat <<'EOF'
- Key change 1
- Key change 2
- Key change 3

Reviews: N/N addressed
Tests: X passed (Y% cov)
Refs: Task N, Req M
EOF
)"

对于 develop → main 合并，运行相同的命令，但不带 --delete-branch。

合并策略：始终使用 --merge（合并提交），绝不 squash 或 rebase。

7. 合并后清理

同步接收合并的分支（PR 的基分支），而不总是同步 develop：

BASE=$(gh pr view $PR --json baseRefName -q .baseRefName)
git checkout "$BASE" && git pull origin "$BASE"

8. 检查里程碑是否完成

如果此 PR 有关联里程碑，请检查所有事项现在是否都已关闭：

MILESTONE=$(gh pr view $PR --json milestone -q '.milestone.number // empty')
if [ -n "$MILESTONE" ]; then
  gh api repos/$REPO/milestones/$MILESTONE \
    --jq '"Open: \(.open_issues) | Closed: \(.closed_issues) | \(.title)"'
fi

• 如果 open_issues == 0：通知用户，并询问是否关闭里程碑

gh api repos/$REPO/milestones/$MILESTONE --method PATCH --field state="closed"

• 如果 open_issues > 0：报告剩余未完成事项的数量。无需采取任何操作。
• 未经用户明确确认，绝不要自动关闭里程碑。

合并消息格式

采用简洁格式，保持 Git 日志清晰：

- Key change 1 (what was added/fixed)
- Key change 2
- Key change 3

Reviews: 7/7 addressed (Gemini 5, Codex 2)
Tests: 628 passed (88% cov)
Refs: Task 8, Req 14-15

• 变更最多列出 3–5 个要点
• 评审摘要、测试结果和任务引用各占一行
• 不要使用标题（##），不要写冗长的章节
• 总计：最多约 10 行

重要规则

• 始终在合并前运行测试、Lint 和 CI 检查
• 始终确认所有评审评论都已回复
• 始终在合并前检查里程碑分配情况（如果缺少则提醒，但不要阻止合并）
• 始终（对于包含 CHANGELOG 的仓库）确认其中记录了此次合并发布的每一项行为变更提交；如果有遗漏，立即停止并报告
• 始终在执行合并前征得用户确认
• 始终使用合并提交（--merge），绝不使用 squash/rebase
• 始终仅在将主题分支（feature/fix/等）合并到 develop 时删除头部分支
• 绝不删除 develop 或 main。在将 develop 合并到 main 时，省略 --delete-branch，且绝不建议删除分支
• 始终在合并后检查里程碑完成情况，并报告未完成事项数量
• 绝不在测试、Lint 或 CI 检查失败时合并
• 绝不跳过用户确认
• 绝不在未经用户明确确认的情况下关闭里程碑
• 绝不通过此技能回复 PR 评论——请使用 github-pr-review
• 如果存在尚未回复的评论，立即停止合并，并引导用户使用评审技能