Skip to content

docs(harness): commit 规范分两层,squash 用 PR description #2647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DoctorReid merged 2 commits into from
Aug 3, 2026
+25 −5
Merged

docs(harness): commit 规范分两层,squash 用 PR description #2647

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b95ac8
docs(harness): commit 规范分两层,squash 用 PR description
DoctorReid Aug 3, 2026
6e2b2eb
docs(harness): 按 review 调整 commit 规范(squash/merge commit 都用 PR desc 等)
DoctorReid Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,9 @@ uv run --env-file .env ruff check --fix src/你修改的文件.py
- **同开关联 PR**:开主仓 PR 时同开测试仓 PR,PR 描述互相挂链接(**跨仓链接用 `OneDragon-Anything/<repo>#<N>` 或完整 URL,禁裸 `#N`** —— 裸 `#N` 会被 GitHub 识别成本仓而非目标仓);别让测试仓分支挂着改动却没开 PR(主仓合了才补测试仓 = 漏)。
- **合并顺序:测试仓先 → 主仓后**(主仓 main 的 test-check clone 测试仓 main,测试仓先合才稳)。
- 如果用户明确要求切换分支，先 `stash` 当前改动，再切换。
- **commit message 分两层**(规范依据 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)):
- **单个迭代 commit**:写清这一步干嘛即可,不强制格式;建议带 type 前缀(`fix:` / `docs:` / `chore:` / `wip:`)方便扫,但不要求 scope / 长度 / body。判据:不看 diff 也能知道这步干了啥(✅ `fix: Y 坐标分母` ❌ `update`)。
- **需要额外提供 commit message 的 merge**(squash、merge commit 等,merge 时要写/确认最终 message 的):严格 Conventional Commits —— message = `type(scope): subject`;description 开头一段 why(每行 ≤72,写 what/why 不写 how,不列改动清单)+ `##` 关联(issue / 测试仓 PR)。type ∈ `feat / fix / docs / refactor / test / chore / perf / build / ci / style`,scope = 模块,subject 祈使句 ≤50、无句号,PR/issue 号不进 subject(GitHub squash 自动追加 `(#NNNN)`)。仓库 squash 设置用 PR description(第一个 `##` 前 = commit body),收尾时按 `zzz-od-dev-pr-finishing` skill 维护 title + desc;不重复 CodeRabbit Walkthrough,不写 `Co-Authored-By`。
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
- Review 关注逻辑错误、运行时崩溃、死循环、资源泄漏；不要为风格问题大改现有代码。
- 提交 PR 后，review comment 需要逐条回复或修正。

Expand Down
15 changes: 12 additions & 3 deletions skills/zzz-od-dev-pr-finishing/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ description: 当用户要把已开的 PR 推到「完善可合并」、处理 PR
1. **CI checks**:required 全 pass;**条件触发类 check 的 `skipping` 不算失败**(如打包/签名/发布类 check,PR 上不触发属正常)—— 只看 required 是否绿。
2. **自动化 review 完成且无新建议**:CodeRabbit 这轮 review 跑完。⚠️ **增量 review 无新建议时,它不建 check run、也不留 review 记录** —— 完成态靠它回复的 issue comment(对 `@coderabbitai review` / 自动 review 的 ack,body `<details>` 里 `✅ Action performed` → `Review finished`)确认,结合 0 unresolved。别因 `reviews` 没新记录 / 没 check run 就以为没 review(见流程 1)。
3. **讨论区无 unresolved thread**:每条都处理过(每条最终都要 resolve,不留 —— 见流程 2)。
4. **关联 PR(跨仓)也都 done**:跨仓同分支的关联 PR(如测试仓 PR)也按本 skill 收尾全清;**都 done 才合**(见流程 6)。
4. **关联 PR(跨仓)也都 done**:跨仓同分支的关联 PR(如测试仓 PR)也按本 skill 收尾全清;**都 done 才合**(见流程 7)。

## 流程

Expand Down Expand Up @@ -56,12 +56,21 @@ resolve 前确保 CodeRabbit 对这条「说完话了」,不抢它的判断、
### 4. push → 迭代
每次 push 触发 review 重审 + CI 重跑,**可能新提 comment**。重复 1-3,直到「review 完成 + 无 unresolved + checks 绿」稳定。若连续 2 轮仍冒新 comment 或无法收敛 → 停下来问人,别死循环。

### 5. 合并前
### 5. 整理 PR title + description(供 merge commit message,合并前)
需要额外提供 commit message 的 merge(squash、merge commit 等)时,PR title + desc 是最终 message 的来源(仓库 squash 设置已用 PR description,第一个 `##` 前 = commit body)。收尾时把 title + desc 维护成严格 Conventional Commits 的 message(规范见 AGENTS.md「commit message 分两层」):
- **title**:`type(scope): subject`(≤50、祈使句);已合规则不动。
- **description**:开头一段总结(why / 关键决策,2-5 行,每行 ≤72;不列改动清单、不写 `Co-Authored-By`)+ `##` 后的关联(issue / 测试仓 PR 链接)。第一个 `##` 前 = squash commit body。
- 命令:`gh pr edit <PR> --title "type(scope): subject" --body "..."`(body 多行用 heredoc 或临时文件传)。
- **关联 PR(测试仓)**:同样整理(两仓 squash 设置都已改 `PR_BODY` 时)。
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
- **时机**:只在收尾(done、合并前)做一次,不每次 push。
- AI 不执行 merge;这步只把 desc 准备好,merge 由用户决定(边界同下一条「合并前」)。
Comment on lines +59 to +66

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

将项目专属流程细节移到 design.md。

本段新增了 zzz-od-test、PR_BODY、两仓 squash 设置和具体 GitHub 命令。这些内容属于本仓库的实现细节，不是可复用的方法论。请在 SKILL.md 中改用 <test-repo>、<remote>、<branch> 等通用占位符，并将具体规则保留在 design.md。

As per coding guidelines：SKILL.md 应写方法论，不写与外部代码强相关的具体内容；具体例子和踩坑放入 design.md。

Based on learnings：skills/**/SKILL.md 只描述可复用方法论，特定 workflow、远端和分支细节应放入 design.md。

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/zzz-od-dev-pr-finishing/SKILL.md` around lines 59 - 66, 将 SKILL.md 第 5
节改为可复用的方法论：用 <test-repo>、<remote>、<branch> 等通用占位符替代 zzz-od-test、PR_BODY、两仓
squash 设置及具体 gh pr edit 命令；把这些仓库专属流程、命令和示例移至对应的 design.md，并保留通用的 PR
标题、描述维护时机及合并职责说明。

Sources: Coding guidelines, Learnings


### 6. 合并前
`mergeable` 要 `MERGEABLE`、非 `DIRTY`;dirty → rebase 到目标分支。是否 merge / 合并方式不在本 skill 范围(见 superpowers:finishing-a-development-branch)。

**合并后清理(提示,不主动)**:PR 合并后,可**提示**用户删除该 PR 的本地 + remote 分支(`git branch -d <branch>` + `git push origin --delete <branch>`)。只提示,**不主动执行**——分支可能还在用(回看 / cherry-pick)、或用户想保留,由用户确认时机。`gh pr merge --delete-branch` 会同时删 remote + 本地,但只删当前 PR 的;之前遗留的分支要手动清。

### 6. 关联 PR(跨仓)协同
### 7. 关联 PR(跨仓)协同
本项目跨仓:主仓 PR 常带配套**测试仓 PR**(同分支名,主仓描述带测试仓 PR 链接)。
- **关联 PR 不只看 open PR(由真实事故提炼)**:测试仓改动可能挂在同分支但**没开 PR**(改动没经 review)→ `gh pr list --head <分支>` 查 open PR 为空**不等于**"无配套"。收尾主仓前用 git 验证测试仓同分支有无未合改动:`git -C zzz-od-test fetch https && git -C zzz-od-test log https/main..<同名分支>`(有输出 = 测试仓有未合改动,必须先开 PR 合掉再合主仓,否则主仓 main 的 test-check 跑测试仓 main 缺这些测试 = CI 通过但测试缺失;无输出 = 确实无配套)。
- **一起收尾**:关联 PR 都按本 skill 走(CI/review/unresolved 全清),不只当前 PR。
Expand Down
9 changes: 8 additions & 1 deletion skills/zzz-od-dev-pr-finishing/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,14 @@
8. **push 后不自动触发 = 被 auto-pause(非偶发)**:CodeRabbit 有 `reviews.auto_review.auto_pause_after_reviewed_commits` 机制 —— PR 活跃开发 / 频繁 commit 时**自动暂停** review,之后**每次 push 都不自动触发**(不是偶尔)。检测:PR 有 `Reviews paused` comment(grep body 含 `Reviews paused` / `review paused`)。暂停下两命令语义不同:`@coderabbitai review` = **单次**触发(保持暂停,下次 push 仍不自动);`@coderabbitai resume` = **恢复**自动(之后 push 自动触发,ack `Reviews resumed.`)。ack 里那句「此命令仅在自动 review 暂停时适用」就是在提示当前处于暂停态。预防:调 `.coderabbit.yaml` 的 `auto_pause_after_reviewed_commits` 阈值 / 关闭。实战:PR 2419 从 7-01 起被 auto-pause,故每轮 push 都要手动补 —— 曾误判为「偶尔不触发」,实际是**始终暂停**。
9. **增量 review 无建议时 API 无痕**:增量 review 没新建议时,CodeRabbit 不建 check run、不留 review 记录,只回复一条 issue comment(`✅ Action performed` / `Review finished`)。故「review 完成」的可靠判据是这条 ack comment 的 body,不是 check run / reviews(实战:PR 2419 增量 review 完成但 API reviews 停在上一天、该 commit 无 CodeRabbit check run)。**手动 @ 后 ack 的演变**:ack comment 先回 `Review triggered`(review 进行中),真正完成后 CodeRabbit **编辑同一条** comment 为 `Review finished`(不另发新 comment)。`triggered` 是中间态 —— 判完成必须看到 `finished`,别把 `triggered` 当结果(实战:PR 2419 bf2ebfea 手动 @ 后 06:38Z 回 triggered,review 完成后同条被编辑成 finished)。
10. **时区**:GitHub API 时间是 UTC(`Z` 后缀),显示给用户前转本地(维护者 UTC+8);避免时间串造成困惑。
11. **关联 PR 用 git 验证,不只查 open PR**:`gh pr list --head <分支>` 查 open PR 为空 ≠ 无配套 —— 测试仓改动可能挂在同分支但没开 PR(有改动但没开 PR)。收尾主仓前必须 `git -C zzz-od-test fetch https && git -C zzz-od-test log https/main..<同名分支>` 验证无未合改动。**为什么不用 open PR 判**:PR #2608 收尾时查测试仓同分支 open PR 为空就判"无配套"、直接合了主仓,事后才发现测试仓分支有 11 个未合 commit(有改动、没开 PR)→ 补救才开测试仓 #35。根因:open PR 是「是否已开 PR」的判据,不是「是否有配套改动」的判据;后者要看 git 分支。该方法进 SKILL.md §6;配套的预防约束(开发阶段就同开关联 PR)进 AGENTS.md「提交流程与协作边界」+ development_workflow.md §4(泛化到非游戏流程改动)。
11. **关联 PR 用 git 验证,不只查 open PR**:`gh pr list --head <分支>` 查 open PR 为空 ≠ 无配套 —— 测试仓改动可能挂在同分支但没开 PR(有改动但没开 PR)。收尾主仓前必须 `git -C zzz-od-test fetch https && git -C zzz-od-test log https/main..<同名分支>` 验证无未合改动。**为什么不用 open PR 判**:PR #2608 收尾时查测试仓同分支 open PR 为空就判"无配套"、直接合了主仓,事后才发现测试仓分支有 11 个未合 commit(有改动、没开 PR)→ 补救才开测试仓 #35。根因:open PR 是「是否已开 PR」的判据,不是「是否有配套改动」的判据;后者要看 git 分支。该方法进 SKILL.md §7;配套的预防约束(开发阶段就同开关联 PR)进 AGENTS.md「提交流程与协作边界」+ development_workflow.md §4(泛化到非游戏流程改动)。
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

12. **PR description 作为 squash 总结(issue #2615)**:仓库 squash 设置改用 PR description(非拼 commit);收尾时按 AGENTS.md commit 规范把 title + desc 维护成总结。
- **规范分层(决策 7)**:单个迭代 commit 宽松 / 需要额外提供 commit message 的 merge 严格 Conventional Commits,两层规范都在 AGENTS.md;本 skill 收尾动作只管严格层(PR title + desc,即 merge 最终 message 的来源)。
- **为什么不把七规则写进本 skill**:七规则读者是所有写 commit 的 AI,不止收尾 AI;埋在本 skill(仅收尾触发)里其他场景看不到 → 规范进 AGENTS.md(每会话进 context,单一源),本 skill 只放收尾动作 + 指针。
- **依赖 GitHub 截断**:`PR_BODY` 模式取 desc 第一个 `##` 前内容作 commit body,`##` 后不进 commit;实施时用一个 PR 实测确认(降级:若取整段,desc 只放 commit message 内容,关联移 PR comment)。
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

@ShadowLemoon ShadowLemoon Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

实测是取整段desc的

- **不重复 CR Walkthrough / 不写 Co-Authored-By**:改动清单 CR 已生成,trailer GitHub squash 自动汇总。
- **AI 不 merge**:只准备 desc,merge 由用户(与现有边界一致)。

## 落点

Expand Down
Loading