约定式提交 原创

一、什么是约定式提交？

约定式提交（Conventional Commits）是一种轻量级的提交信息规范。它要求提交信息遵循一套简单的人类和机器可读的结构。其核心价值在于为自动化工具（如版本发布机器人、变更日志生成器）提供明确的语义依据。

二、核心价值与优势

• 自动化版本发布：通过提交类型（fix、feat）自动推断下一个语义化版本号。
• 自动生成变更日志：工具能准确识别新功能、修复和破坏性变更，生成结构化的发布说明。
• 清晰的协作历史：迫使开发者提交原子化、有意义的变更，让项目历史一目了然。
• 降低心智负担：标准化的格式消除了“怎么写提交信息”的犹豫，让提交变成填空题。

三、规范结构详解

<类型>[作用域]: <描述>
空行
[正文]
空行
[页脚]

1. 页眉

这是最核心的部分，格式要求严格。

• <类型>：标识本次提交的意图。常用类型有：
  • feat：新功能。对应语义化版本中的 MINOR 版本。
  • fix：修复 Bug。对应语义化版本中的 PATCH 版本。
  • docs：仅文档变更。
  • style：不影响代码逻辑的变更（如空格、分号、格式）。
  • refactor：既不修复 Bug 也不增加新功能的代码重构。
  • perf：提升性能的代码变更。
  • test：增加或修改测试。
  • build：影响构建系统或外部依赖的变更。
  • ci：CI/CD 配置文件和脚本的变更。
  • chore：其他不修改 src 或 test 文件的杂务。
  • revert：回退之前的提交。
• [作用域]：用括号包裹，表示此次变更影响的范围或模块。
  • 示例：feat(lang): add english language
  • 示例：fix(parser): correct parsing of floating point numbers
• <描述>：对本次变更的简短说明。
  • 不超过50个字符，保持简洁。
  • 使用祈使句（动词原形开头）。一个检查方法是，这句话应该能完整地回答 "If applied, this commit will..."（如果应用这个提交，它会...）这个问题。
  • 首字母不需要大写，结尾也不加句号。

2. 正文

这是一个可选的自由格式文本，与页眉之间必须空一行。如果改动比较复杂，就需要在正文中写清楚“为什么改”和“怎么改”。同样需要使用祈使句，现在时态。

3. 页脚

位于正文之后，也须空一行。可以包含两类信息：

• 破坏性变更：必须以 BREAKING CHANGE: 开头，后跟一个空格和描述。表示此提交引入了不兼容的 API 修改，对应语义化版本中的 MAJOR 版本。也可在页眉的类型/作用域后加 ! 来快速标记，如 feat!:。
• 关联议题：用于关闭或关联 Github 中的 Issue 等。
  • 关联并关闭 (close/fix/resolve)：close #123, #456
  • 关联不关闭 (ref/see)：ref #233

四、规范示例

示例 1：最简单的规范提交

docs: correct spelling of CHANGELOG

示例 2：带正文和页脚的提交

fix(api): resolve race condition in user creation

This change introduces a mutex lock to prevent concurrent
requests from creating users with the same email address.
The fix ensures idempotency and data integrity.

Closes #421

五、工具与生态系统

手动遵循规范容易出错，因此生态中诞生了大量辅助工具。

因为我使用 WebStorm 开发，所以这里推荐 Conventional Commit 插件。安装后在 提交 的 提交消息 输入框上会增加三个按钮：

• 创建提交消息
• 清理提交历史
• 提交消息历史记录

六、常见问题

Q: 为什么一定要用祈使句？

A: Git 本身也是用祈使句生成提交的（如 Merge branch ‘feature’）。这保持了与 Git 自身操作的一致性，将一次提交视为对代码库的一道命令或指令。

Q: 必须用英文吗？

A: 为了全球协作和工具链兼容，建议使用英文，但中文也能被工具解析。