Commit Message 规范
规范这种事一般是赢家通吃的,也没什么好标新立异的,好用就行了。
基本上唯一的选择,约定式提交(Conventional Commits)规范。
(本文写就时)最新的文档。
标准格式
<type>(<scope>): <subject>
<body>
<footer>
类型 <type>
- 当一个提交为实现了新特性时,必须使用
feat类型。 - 当一个提交为修复了 bug 时,必须使用
fix类型。
原文
Select the type of change that you're committing:
feat: A new featurefix: A bug fixdocs: Documentation only changesstyle: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)refactor: A code change that neither fixes a bug nor adds a featureperf: A code change that improves performancetest: Adding missing tests or correcting existing testsbuild: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)chore: Other changes that don't modify src or test filesrevert: Reverts a previous commit
翻译
本次修改是一个什么类型的 commit:
feat: 增加新功能fix: 修复 bug
上面这两种标签是固定的,以下都是根据 Angular 约定 推荐使用的标签:
docs: 文档改动style: 代码风格上的修改(对代码含义没有任何影响那种,比如空格、缩进、分号等)refactor: 重构(代码内容变了,但既没有新增功能也没有修 bug)perf: 性能优化test: 测试相关build: 构造工具以及外部依赖相关(比如 gulp, broccoli, npm)ci: CI 相关配置文件及脚本(比如 Travis, Circle, BrowserStack, SauceLabs)
其他常用的标签:
improvement: 对当前实现进行改进而没有新增功能或修复 bug 的提交chore: 其他没有提到的不会动源代码或者测试文件的改动revert: 撤销之前的 commit
作用域 <scope>
可选项。
必须是名词。
描述改动的范围,想了下如果涉及多个模块还是分多次提交比较好,方便代码版本追踪和维护。
简述 <subject>
一句话,说重点。
范式:
- 动词开头,而且是第一人称一般现在时,
changeYES,changed/changesNO - 首字母小写
- 结尾不用标点
总之就是把它当短语。
正文 <body>
可选项。
本次改动的详细描述,可以写:
- 改动之前的情况
- 改动之后的效果
- 修改动机
脚注 <footer>
可选项。
一般放的两类信息:
- 如果是破坏性变更(break changes)要以
BREAKING CHANGE开头然后指明弃置的内容 - 影响 issues
如果有破坏性变更,第一行 : 之前可以接上 ! 提醒注意;但如果加了 !,<body> 或者 <footer> 内必须包含 BREAKING CHANGE: description。
总结
以上范式不是定着好玩或者仅仅只是为了满足强迫症看着爽的。
Conventional Commits 定出来除了约定俗成一看就懂以外,它真正 convenient 的地方在于如果坚持使用规范的话,可以直接根据 commit message 记录生成 changelog。
相关工具
Commitizen
PHP 版 Commitizen
检查提交信息是否符合规范的工具 用 Go 写的,支持在 CI 的 Docker 镜像中使用