目前大多数的公司和开发者都选择 Git 作为版本控制工具,这意味着每个开发者每天都在使用 Git,都会使用 Git Commit Mesasge ,虽然 Git Commit Message 看起来很简单,但实际上却异常重要。每个接触项目的开发者通过 Git Commit Message 快速了解当次提交的信息,比如新增了那些功能、解决了那些 Bug、优化了那些问题等。所以一套有效 Git Commit Message 管理规范是很有必要的。也对项目有着更好的维护性。
规范化 Git Commit Message 不仅仅有以上的好处,还有更多的好处,比如:
- 自动化生成 changelog
- 基于提交的类型,自动决定语义化的版本变更
- 触发构建和部署流程
- 使参与者更容易的探索结构化的提交历史,降低贡献项目的难度
Conventional Commits
Conventional Commits 的书写规范 就是在 Angular 规范的基础上进一步总结而成。
标准格式
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Type
type 用于表示此次改动的类型,目前常用的主要有以下几种:
- feat:新功能(feature)表示在代码库中新增了一个功能
- fix:表示在代码库中修复了一个 bug
- docs: 文档(documentation)的新增、修改、删除等操作
- style: 格式化, 缺失分号等; 不包括生产代码变动
- refactor: 重构代码(即不是新增功能,也不是修改 bug 的代码变动)
- perf: 性能优化
- test: 添加缺失的测试, 重构测试, 不包括生产代码变动
- chore: 更新 grunt 任务(构建过程或辅助工具的变动)等; 不包括生产代码变动
如果 type 为 feat 和 fix,则该 commit 将肯定出现在 Change log 之中。其他情况(docs、chore、style、refactor、test)由提交者自己决定,要不要放入 Change log,通常情况建议是不要。
scope
optional 表示 scope 可以选择填写也可以不选择填写。
scope 用于说明 commit 影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同。
description
简明扼要描述本次提交的内容,首字母无需大写,结尾不加句号,尽量不超过 50 个字符
body
详细描述本次提交,比如此次变更的动机,如需换行,则使用 |
。
footer
描述与之关联的 issue 或 break change。一般使用于不兼容变动或者关闭 issue 或者 break change。
注意事项
- 提交必须以类型为前缀,该类型由名词、、
feat
等组成fix
,后跟可选范围、可选!
,以及必需的终端冒号和空格。 -
feat
当提交向您的应用程序或库添加新功能时,必须使用该类型。 -
fix
当提交代表您的应用程序的错误修复时,必须使用该类型。 - 可以在类型之后提供范围。范围必须由一个名词组成,描述代码库的一部分,用括号括起来,例如,
fix(parser):
- 描述必须紧跟在类型/范围前缀之后的冒号和空格之后。描述是代码更改的简短摘要,例如,修复:字符串中包含多个空格时的数组解析问题。
- 可以在简短描述之后提供更长的提交主体,提供有关代码更改的附加上下文信息。正文必须在描述之后开始一个空行。
- 提交主体是自由格式的,可以由任意数量的换行符分隔的段落组成。
- 一个或多个页脚可以在正文之后提供一个空行。每个页脚必须由一个单词标记组成,后跟一个
:<space>
或<space>#
分隔符,后跟一个字符串值(这受到 **git 预告片约定**的启发)。 - 页脚的标记必须用来
-
代替空白字符,例如,Acked-by
(这有助于将页脚部分与多段正文区分开来)。例外BREAKING CHANGE
,它也可以用作标记。 - 页脚的值可以包含空格和换行符,并且当观察到下一个有效的页脚标记/分隔符对时,解析必须终止。
- 必须在提交的类型/范围前缀中或作为页脚中的条目指示重大更改。
- 如果包含在页脚中,则重大更改必须由大写文本 BREAKING CHANGE 后跟冒号、空格和描述组成,例如BREAKING CHANGE:环境变量现在优先于配置文件。
- 如果包含在类型/范围前缀中,则中断更改必须由
!
紧接在:
. 如果!
使用,BREAKING CHANGE:
可以从页脚部分省略,提交描述应用于描述重大更改。 - 您的提交消息中可以使用
feat
和以外的类型,例如docs: updated ref docs。fix
- 构成常规提交的信息单元不得被实施者视为区分大小写,但必须为大写的 BREAKING CHANGE 除外。
- 当用作页脚中的标记时,BREAKING-CHANGE 必须与 BREAKING CHANGE 同义。
示例
提交带有描述和重大更改页脚的消息
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for
提交消息 !
以引起对重大变化的关注
feat!: send an email to the customer when a product is
提交有范围的信息并 !
引起对重大变化的关注
feat(api)!: send an email to the customer when a product is
同时提交消息 !
和 BREAKING CHANGE 页脚
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
提交没有正文的消息
docs: correct spelling of CHANGELOG
提交具有范围的消息
feat(lang): add Polish language
提交带有多段正文和多个页脚的消息
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
参考文档:全栈修仙之路