约定式提交与发布 是做什么的？
概述
提交消息是一种机器可读的接口，而非仅仅是一段文字。自动版本管理和变更日志生成都会解析它们；格式错误的消息会导致错误的公开发布版本或失败的发布。在小处遵循规范（一条格式正确的消息）将自动带来大处的正确性（准确的变更日志、正确的版本递增）。
格式
<类型>(<范围>): <描述>
| 类型 | 作用 / 用途 |
|---|---|
feat | 新功能 — 次版本号（minor） 递增 |
fix | 错误修复 — 修订号（patch） 递增 |
docs | 仅文档变更 |
chore | 维护、依赖、配置 |
refactor | 保持行为的代码变更 |
test | 仅测试 |
ci / build | 流水线 / 构建系统变更 |
- 祈使语气： “add X”，而不是“added X”或“adds X”。
- 破坏性变更：
feat!:或BREAKING CHANGE:脚注 — 触发主版本号（major） 递增。 - 范围（Scope） 可选，但鼓励使用：
feat(auth):、fix(db):。
关键细节
- 类型与版本的关联意味着错误地将
feat写成fix会导致错误的版本发布。 请有目的地选择类型：“add” = 新功能，“update” = 对现有功能的增强，“fix” = 错误修复。 - 压合合并： PR 标题会成为最终发布的提交。它本身必须是一个有效的约定式提交，否则发布将出错。
- 人类作者语气。 不允许 AI/助手署名、
Co-authored-by尾注或“由...生成”的脚注。提交应表现为由人类编写。
常见辩解
| 借口 | 现实 |
|---|---|
| “这条消息其实无关紧要” | 它驱动变更日志和版本号。它在机械层面上至关重要。 |
“对于这个功能，用 chore 也差不多” | chore 不会触发版本递增；用户将无法在你的发布中获得该功能。使用正确的类型。 |
| “我稍后会修复 PR 标题” | 在压合合并中，标题在合并时就是最终的。请在合并前修复它。 |
“Co-authored-by 尾注没什么害处” | 项目规则禁止 AI 署名，没有例外。 |
红色警报 — 立即停止
- 没有类型前缀的提交消息
- 对增加或修复用户可见行为的内容使用了
chore/docs - 压合的 PR 标题不是有效的约定式提交
- 任何 AI 署名或
Co-authored-by行
强制执行：
- PR 标题 — 在 CI 中验证，阻塞型（使用
amannn/action-semantic-pull-request）。 在压合合并时，标题就是最终发布的提交，因此这是最重要的关卡。 - AI 署名 — 一个阻塞型的“无 AI 署名”任务会拒绝包含 Claude/Anthropic 的
Co-authored-by尾注以及“Generated with [Claude…]”脚注，无论是分支提交还是 PR 主体（PR 主体会成为压合提交的主体）。人类作者的Co-authored-by尾注不受影响。 - 分支提交体 — 有意不进行 lint 检查。压合合并会丢弃这些提交体，因此它们永远不会进入变更日志。如果你改用合并提交，请添加 commitlint。
已知缺口： 如果某个提交的作者是代理账户，GitHub 在压合时会自动生成一个 Co-authored-by 尾注——这是在 PR 检查运行之后。上述关卡无法捕获它。不要以代理身份提交。
完整理由：请参阅章程第三条，附于 engineering-constitution/references/engineering-constitution.md。