约定式提交是一种用于对Git的提交信息的轻量级规范,其创造了一套构建明确的提交历史信息的规则,不仅方便向他人传达变化的性质,而且对构建自动化工具非常友好。
完整的规范可以在这里阅读,目前(2021年7月)最新的是v1.0.0版本。以下是简单的摘录。
基本介绍
提交信息满足以下结构:
1 2 3 4 5
| <type>[optional scope]: <description>
[optional body]
[optional footer(s)]
|
type表示本次提交的分类,约定如下:
- fix: 修复了一个bug(这和语义化版本中的
PATCH
相对应)
- feat: 新增了一个功能(这和语义化版本中的
MINOR
相对应)
- BREAKING CHANGE: 在脚注中包含
BREAKING CHANGE:
或 <type>[optional scope]
后面有一个 !
的提交,表示引入了破坏性 API 变更(这和语义化版本中的 MAJOR
相对应)。 破坏性变更可以是任意 type
的提交
- 另外,除
fix:
和 feat:
之外,也可以使用其它提交 类型 ,例如 @commitlint/config-conventional(基于 Angular 约定)中推荐的 build:
、chore:
、ci:
、docs:
、style:
、refactor:
、perf:
、test:
,等等。这些类型对应的使用场景分别为
- build: 影响构建系统或外部依赖的修改,例如
npm
等
- chore: 不涉及到生产代码的配置文件的修改,某种程度上包含
build:
和 ci:
的含义,个人更倾向于用 chore:
- ci: CI配置文件或脚本的修改
- docs: 文档相关修改
- style: 不涉及到生产代码含义的修改,例如空格、缩进、格式、分号等
- refactor: 既没修复bug又没添加功能的重构修改,例如重命名变量等
- perf: 提升性能的修改
- test: 有关测试相关的代码的修改
- 脚注中除了
BREAKING CHANGE: <description>
,其它条目应该采用类似 git trailer format 这样的惯例
其它提交类型在约定式提交规范中并没有强制限制,并且在语义化版本中没有隐式影响(除非它们包含 BREAKING CHANGE
)。 可以为提交类型添加一个围在圆括号内的范围,以为其提供额外的上下文信息。例如 feat(parser): adds ability to parse arrays.。
示例
包含了描述并且脚注中有破坏性变更的提交说明
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
| refactor!: drop support for Node 6
|
包含了 ! 和 BREAKING CHANGE 脚注的提交说明
1 2 3
| refactor!: drop support for Node 6
BREAKING CHANGE: refactor to 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
| fix: correct minor typos in code
see the issue for details
on typos fixed.
Reviewed-by: Z Refs #133
|