chinese-commit

中文 commit 规范

何时用

• 准备执行 git commit 前，需要撰写 commit message 时。
• 对已有 commit message 做 review 或修改时。
• 在 PR 描述中引用 commit 列表，需要判断某条消息是否清晰时。
• 给团队新成员讲解项目提交规范时。

核心规则

1. 格式 = type(scope): 中文主题

规则： type 必须用英文关键字（feat / fix / docs / refactor / test / chore / perf），冒号后的主题用中文，且不超过 50 个字。

为什么： AI 最常见的错误有两种：一是整行全写中文（新增功能：用户登录），导致 CI 的 commit-lint 规则直接报错；二是 type 用中文近义词（特性、修复）或随意缩写（f、upd），让 git log --oneline 的过滤脚本无法识别。格式不统一还会导致自动生成 CHANGELOG 时分类错误，把 bug 修复误放进"新功能"节。

怎么做：

• type 只从以下七个中选一个：feat（新功能）、fix（缺陷修复）、docs（文档）、refactor（重构，不改行为）、test（测试）、chore（构建/工具链）、perf（性能优化）。
• scope 写在圆括号内，可省略，但存在时必须用真实模块名（见规则 5）。
• 冒号后面跟一个空格，然后是中文主题，不加句号。

---

2. 主题写"做了什么"，用祈使句

规则： 主题用一句祈使句描述本次变更的核心动作，不写流水账，不写"修改了一些文件"之类的废话。

为什么： AI 极容易生成这种主题：更新了登录模块的相关代码——这句话在任何 commit 上都成立，完全没有信息量。另一类错误是记流水账：修改了 auth.py，删除了多余的注释，调整了变量名，顺便加了一个空行。主题不是 diff 摘要，是对"本次提交解决了什么问题"的一句话答案。读 git log --oneline 时，好的主题应当让人一眼知道"要不要点进这个 commit 看细节"。

怎么做：

• 问自己：「这个 commit 的目的是什么？」把答案压缩成一句话。
• 动词放句首，例如：修复、新增、删除、提取、替换、禁用。
• 不带末尾句号；不用被动句（不写"被修复了"）。
• 超过 50 字说明你在一次 commit 里做了多件事，应当拆分（见规则 4）。

---

3. 正文只在"为什么"不显然时写

规则： commit 正文（body）用来解释动机与权衡，而不是复述 diff 的内容。若改动理由一眼即明，正文可省略。

为什么： AI 倾向于把 diff 内容逐行翻译成正文，例如：将 token_expiry < now 改为 token_expiry <= now——这完全没有价值，读者直接看 diff 就能得到这个信息。真正有用的正文是：旧逻辑在 token 恰好等于当前时间时不视为过期，导致极少数请求绕过鉴权；改为 <= 后临界情况被正确拦截。 这类信息只存在于作者脑子里，不写下来就永久丢失。

怎么做：

• 主题行与正文之间空一行（git 规范要求）。
• 正文用自然段落，每行不超过 72 字，方便 git log 展示。
• 只写"为什么这样改"和"考虑过哪些替代方案、为何放弃"，不复述 diff。
• 如果有关联的 issue 或 PR，在正文末尾用 Closes #123 / Refs #456 标注。

---

4. 一次只提一件事

规则： 一个 commit 只做一件逻辑上内聚的事；功能、修复、格式整理混在一起时，必须拆成多个 commit。

为什么： AI 在帮用户完成任务时容易"顺手"把格式清理、变量重命名、无关 bug 修复一并提交。这类混合 commit 带来三个具体问题：① git bisect 时无法精确定位引入 bug 的节点；② cherry-pick 到其他分支时会带入不需要的副作用；③ code review 时 reviewer 不知道应该关注功能正确性还是格式合规，两件事互相干扰。

怎么做：

• 在提交前用 git diff --staged 扫描暂存区：确认每一处修改都服务于同一个目的。
• 发现夹带了无关改动（例如顺手修了 typo），用 git add -p 把它们拆到单独的 commit。
• 格式化改动（chore: 统一缩进风格）单独提交，绝不与功能 commit 混在一起。