提交信息规范约定

学完这篇你会掌握什么

• 掌握 Conventional Commits 的 <type>(<scope>): <summary> 结构与正文该写什么
• 理解为什么好的提交信息能让 git bisect、git log、CHANGELOG 真正可用
• 识别常见的提交信息误区，并知道在代码评审中怎么纠偏

高质量提交信息不是形式主义，它直接影响回溯效率和发布可读性。

先想一个问题

生产事故后你想回溯是哪个 commit 引入了问题，可历史里全是 fix bug、update 这种 message。git bisect 最后停在一条 commit 上，你却看不出它改了什么——定位根因花的时间比本该有的长得多。问题不是你不会用 Git，而是历史本身不可读。

一个可落地的模板

<type>(<scope>): <summary>

正文建议补两点：

• 为什么改
• 有哪些风险或后续动作

提交前

确定变更范围选择类型前缀编写清晰描述

→git commit

规范结果

可读历史自动分类可生成文档

好的 message 不是写给自己看的，而是写给半年后的自己和同事看的。

示例

fix(auth): reject expired refresh token

Align backend token validation with new TTL rule.
Risk: may increase login retries for stale clients.

团队约定建议

1. summary 用动词开头，尽量在 72 字符内
2. 把“原因”写清，不只写“改了什么”
3. 破坏性变更必须显式标注

!不要把 PR 描述替代 commit 信息

PR 页面会被折叠或丢失上下文，commit 日志才是长期可检索的历史索引。

常见误区

1. “message 写给自己看就行” —— 恰恰相反。半年后的你和同事都靠 git log 与 git bisect 回溯，模糊的 message 会让定位成本翻倍。
2. “一个 commit 顺手塞多个不相关改动” —— 例如同时改了登录逻辑和文档错别字。这样 git revert / git bisect 无法只回退其中一部分，二分排查会失真。
3. “已推送的 commit 用 --amend 改” —— 改写共享历史会让协作者 pull 时冲突。只改本地、未推送的 commit 才用 amend；已推送的用新 commit 修正。
4. “summary 写成 fix: 修bug” —— 没有 scope、没有原因。规范做法是 fix(auth): reject expired refresh token，让人一眼知道影响面。

!--amend 不是撤销，是改写

git commit --amend 会生成一个新的 commit 对象并替换当前 HEAD；已推送到远程的 commit 被改写后，他人历史会出现分叉，需要强制推送且影响所有人。

一次真实事故回溯

# 线上登录失败，需要定位引入问题的 commit
$ git log --oneline -10
a1b2c3d update      # 无法判断改了什么
e4f5g6h fix bug     # 同样没有信息
$ git bisect start <bad> <good>
# 二分最后停在 "update" 上，但 message 看不出它破坏了 token 校验

如果当初写成 fix(auth): reject expired refresh token，事故定位能直接命中，省下大量排查时间。

接下来建议继续看什么

1. commit hygiene
2. prepare commits before pull request
3. small batch review

给你的练习

1. 把你最近一个项目的 5 条历史 commit 改成 Conventional Commits 格式（type(scope): summary + 正文写原因），对比改写前后 git log --oneline 的可读性。
2. 故意把一个“修登录”和一个“改文档错别字”的改动分两次提交，然后用 git bisect 模拟定位，体会单关注点 commit 的优势。
3. 在团队里评审一条 fix: 修bug 类的 message，按本文模板给出改写建议，并说明为什么 scope 和原因缺一不可。

延伸阅读

沿着同一主题继续深入：

• 高级提交信息规范
• 冲突处理惯例专题
• 先 fetch 再同步