为什么要规范化提交?
在多人协作的项目中,我们无法保证每个人对提交信息的准确描述,这可能会造成理解上的困难。而统一的风格和精确的描述,可以方便后期的维护工作,在处理 Bug 的时候也一目了然。如有必要,对于规范的提交信息,也便于使用自动化工具生成开发日志。
总而言之就是方便自己、方便别人、方便机器人。
提交信息结构
提交信息分成:头部、正文、注脚三个部分
text
<类型>[(可选的作用域)]: <主题>
[可选的正文]
[可选的注脚]
提交信息中必须包含类型,一般为下面中的一种
type | description |
---|---|
feat | 新增一个功能 |
fix | 修复一个 Bug |
docs | 变更文档 |
style | 调整代码格式(不影响功能,例如:修改空格、分号、引号格式) |
refactor | 重构代码 |
perf | 改善性能 |
test | 测试 |
build | 变更项目构建或外部依赖(例如:webpack、gulp、npm) |
ci | 更改持续集成软件的配置文件和package.json 中的scripts 命令 |
chore | 变更构建流程或辅助工具 |
revert | 代码回退 |
作用域用来指定本次提交的影响范围,例如可以依据项目的菜单、功能模块或组件划分。
主题就是对提交的简洁描述,必须要有,一般在 50 个字符以内,通常遵循以下规范:
- 动词开头,第一人称现在时
- 结尾不需要句号(.)
- 英文首字母应小写
正文就是对本次提交的详细描述,可以有多行,应该说明修改的原因和更改前后的行为对比。
如果本次提交是突破性变更或关闭缺陷,则需要注脚:
-
突破性变更
当前代码与上一版本相比具有突破性,则注脚以
BREAKING CHANGE:
开头,后面是对变更的描述和变更理由。 -
关闭缺陷
如果本次提交针对特定的 issue,那么可以在注脚中填写需要关闭的的一个或多个 issue。
破坏性提交
在作用域后使用字符!
提醒本次提交引入了破坏性的变更。
也可以选择在提交信息的正文或注脚中使用 BREAKING CHANGE:
,描述具体内容。
规范
- 提交必须包含类型字段前缀,后接可选作用域,必要的冒号和空格,均采用英文半角。
- 作用域使用小括号包裹,英文半角。
- 正文必须在主题结束后空一行开始。
- 正文结束后空一行可以编写一行或多行注脚。
- 可以在类型/作用域后,
:
前使用!
进一步提醒破坏性变更,当有!
时,正文或注脚中必须包含BREAKING CHANGE:
使用示例
示例 1
text
fix(compile): couple of unit tests for IE9
Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.
Closes #392
Breaks foo.bar api, foo.baz should be used instead
示例 2
text
chore(release): v3.4.2
示例 3
text
feat(browser): onUrlChange event (popstate/hashchange/polling)
Added new event to browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available
Breaks $browser.onHashChange, which was removed (use onUrlChange instead)
示例 4
text
chore!: drop Node 6 from testing matrix
BREAKING CHANGE: dropping Node 6 which hits end of life in April