前言
在公司的日常工作当中或者个人的开源项目,将代码提交到代码库时。都会遇到下面这样的对话框,通常都会随便写点内容在里面。
当遇到问题需要回溯的时候就成了给自己造成的麻烦,因为无法通过commit message来非常直观的看到这一次提交了什么,做了哪些修改。这个时候只能一个一个文件打开来看。这个时候如果有规范的提交将会减少不必要的麻烦。
概述
约定式提交规范是一种基于提交信息的轻量级约定。它提供了一组简单规则来创建清晰的提交历史;这更有利于编写自动化工具。通过在提交信息中描述功能、修复和破坏性变更, 使这种惯例与 SemVer 相互对应。
提交说明的结构如下所示:
原文:
代码语言:javascript复制<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
译文:
代码语言:javascript复制<类型>[可选 范围]: <描述>
[可选 正文]
[可选 脚注]
提交说明包含了下面的结构化元素,以向类库使用者表明其意图:
- fix: 类型 为
fix
的提交表示在代码库中修复了一个 bug(这和语义化版本中的PATCH
相对应)。 - feat: 类型 为
feat
的提交表示在代码库中新增了一个功能(这和语义化版本中的MINOR
相对应)。 - BREAKING CHANGE: 在脚注中包含
BREAKING CHANGE:
或 <类型>(范围) 后面有一个!
的提交,表示引入了破坏性 API 变更(这和语义化版本中的MAJOR
相对应)。破坏性变更可以是任意 类型 提交的一部分。 - 除
fix:
和feat:
之外,也可以使用其它提交 类型 ,例如 @commitlint/config-conventional(基于 Angular 约定)中推荐的build:
、chore:
、ci:
、docs:
、style:
、refactor:
、perf:
、test:
,等等。 - 脚注中除了
BREAKING CHANGE: <description>
,其它条目应该采用类似 git trailer format 这样的惯例。
其它提交类型在约定式提交规范中并没有强制限制,并且在语义化版本中没有隐式影响(除非它们包含 BREAKING CHANGE)。可以为提交类型添加一个围在圆括号内的范围,以为其提供额外的上下文信息。例如 feat(parser): adds ability to parse arrays.
。
示例
包含了描述并且脚注中有破坏性变更的提交说明
代码语言:javascript复制feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
包含了 !
字符以提醒注意破坏性变更的提交说明
代码语言:javascript复制feat!: send an email to the customer when a product is shipped
包含了范围和破坏性变更 !
的提交說明
代码语言:javascript复制feat(api)!: send an email to the customer when a product is shipped
包含了 !
和 BREAKING CHANGE 脚注的提交说明
代码语言:javascript复制chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
不包含正文的提交说明
代码语言:javascript复制docs: correct spelling of CHANGELOG
包含范围的提交说明
代码语言:javascript复制feat(lang): add polish language
包含多行正文和多行脚注的提交说明
代码语言:javascript复制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
参考:
- 1.约定式提交官网:https://www.conventionalcommits.org/zh-hans/
- 2.完整提交类型列表: https://github.com/pvdlg/conventional-changelog-metahub#commit-types
- al-commits Conventional Changelog:https://github.com/conventional-changelog/standard-version