定义

当多人参与开发时，对于提交的代码需要有一个标准的格式和规范，这就是Conventional Commits（约定式提交）。

Conventional Commits规范是一个定义提交消息格式的规范，其目的是使提交消息能够清晰、简洁、易于阅读，并且能够自动化生成变更日志。其主要包括两个部分：提交消息的结构与提交消息的类型

提交消息的结构

提交消息包括两个主要部分：头部和主体。头部由三个部分组成：类型<type>、作用域scope和主题description。类型<type>表示此次提交的目的和意图，作用域scope表示此次提交影响的范围，主题description则简要描述此次提交的内容。主体是可选的，可以用于详细描述此次提交的修改内容。

提交消息的结构应如下所示：

1
2
3
4
5
<type>[optional scope]: <description>

[optional body]

[optional footer]

例如，下面是一个符合“Conventional Commits”规范的提交消息：

1
2
3
4
5
sqlCopy codefeat(user): add login functionality

- added a login form to the user page
- updated user service to handle login requests

这个提交消息的类型是“feat”（表示新增功能），作用域是“user”（表示此次提交仅涉及用户模块），主题是“add login functionality”（表示此次提交增加了登录功能）。主体部分body则进一步详细描述了此次提交的修改内容。

提交消息的类型

“Conventional Commits”规范定义了一组常见的提交消息类型，每个类型都表示一种不同的提交目的和意图。这些类型包括：

  • feat：新增功能（feature）
  • fix：修复 bug
  • docs：更新文档（documentation）
  • style：调整代码风格，如改变缩进、空格等
  • refactor：重构代码，既不新增功能也不修复 bug
  • test：新增或修改测试用例
  • chore：更新构建过程、辅助工具等
  • perf: 提高性能的代码更改
  • build: 影响生成系统或外部依赖项的更改 (example scopes: gulp, broccoli, npm)
  • ci: 对 CI 配置文件和脚本的更改 (example scopes: Travis, Circle, BrowserStack, SauceLabs)

BREAKING CHANGE: 在脚注中包含 BREAKING CHANGE: 或 <类型>(范围) 后面有一个 ! 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 MAJOR 相对应）。 破坏性变更可以是任意 类型 提交的一部分

更多类型参考： @commitlint/config-conventional（基于 Angular 约定）

提交消息的脚注

除了头部和类型之外，还有一些可选的标记可以在提交消息中使用，用于提供更多信息或标记本次提交的状态。这些标记包括：

  • BREAKING CHANGE：用于标记本次提交引入了破坏性变更，即可能导致现有代码无法正常运行的修改。
  • CLOSES/FIXES/RESOLVES：用于与问题跟踪系统（如 GitHub Issues）集成，指示本次提交关闭了某个问题或修复了某个 bug。

使用这些标记可以进一步提高提交消息的可读性和自动化程度。例如，下面是一个使用了标记的提交消息示例：

1
2
3
4
5
6
7
8
sqlCopy codefeat: add user search feature

- added a search bar to the user page
- updated user service to handle search requests

BREAKING CHANGE: user service API changed, search endpoint now returns a list of users instead of a single user

Closes #123, Resolves #456

这个提交消息表示新增了用户搜索功能，其中使用了BREAKING CHANGE标记来指示本次提交引入了破坏性变更。另外还使用了Closes和Resolves标记来指示本次提交关闭了两个问题。

最后，使用“Conventional Commits”规范还可以方便地自动生成变更日志。由于每个提交消息都包含了类型和主题信息，因此可以根据提交消息自动分类和汇总变更内容，生成格式化的变更日志。这样可以方便地查看每个版本的变更内容，以及针对特定类型的变更进行统计和分析。

示例

包含了描述并且脚注中有破坏性变更的提交说明

1
2
3
feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

包含了 ! 字符以提醒注意破坏性变更的提交说明

1
feat!: send an email to the customer when a product is shipped

包含了范围和破坏性变更 ! 的提交說明

1
feat(api)!: send an email to the customer when a product is shipped

包含了 ! 和 BREAKING CHANGE 脚注的提交说明

1
2
3
chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

不包含正文的提交说明

1
docs: correct spelling of CHANGELOG

包含范围的提交说明

1
feat(lang): add polish language

包含多行正文和多行脚注的提交说明

1
2
3
4
5
6
7
8
9
10
fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

原文参考

Conventional Commits