Commit Message 规范

前言

在开发过程中经常需要提交代码,提交代码时需要填写 Commit Message(提交说明),否则就不允许提交。但是在每个开发人员提交的格式非常不统一,有中文的,有英文的,还有直接废话文学和直接写11111的,时间久了连开发人员自己都不知道自己表述的修改内容。


Commit Message 规范

社区有多种 Commit Message 的规范,直接参考 angular 的规范。

Angular 规范是一种语义化的提交规范(Semantic Commit Messages)

  1. Commit Message 语义化:Commit Message 都会被归为一个有意义的类型,用来说明本次 commit 的类型。
  2. Commit Message 规范化:Commit Message 遵循预先定义好的规范,比如 Commit Message 格式固定、都属于某个类型,这些规范不仅可被开发者识别也可以被工具识别。

在 Angular 规范中,Commit Message 包含三个部分,分别是 Header、Body 和 Footer,格式如下:


<type>[optional scope]: <description>
// 空行
[optional body]
// 空行
[optional footer(s)]

Header 是必需的,Body 和 Footer 可以省略。在以上规范中,必须用括号 () 括起来, [] 后必须紧跟冒号 ,冒号后必须紧跟空格,2 个空行也是必需的。

Header ,包括三个字段:type(必选)、scope(可选)和 subject(必选)。

type 用来说明 commit 的类型。为了方便记忆,分为 Development 和 Production 共两类

  1. Development 一般是项目管理类的变更,不会影响最终用户和生产环境的代码,比如 CI/CD 流程、构建方式等的修改。遇到这类修改,通常也意味着可以免测发布。
  2. Production 这类修改会影响最终的用户和生产环境的代码。所以对于这种改动,一定要慎重,并在提交前做好充分的测试。

常见 type 分类

类型 类别 说明
feat Production 新增功能
fix Production 修复bug
perf Production 优化性能
refactor Production 其他代码类型的修改,譬如简化代码,重命名,删除冗余代码
style Development 代码格式优化。
test Development 新增或者修改测试用例
ci Development 持续集成和部署相关的改动
docs Development 文档的新增修改
chore Development 其他类型,譬如构建流程,依赖管理辅助功能等

scope 是用来说明 commit 的影响范围的,不同的项目会有不同的 scope ,scope 不适合设置太具体的值,譬如 docs 文档类变更, user 用户模块,pay 支付模块等。

subject 是 commit 的简短描述,必须以动词开头、使用现在时。

Body 是对这次提交的详细描述,Body 部分可以分成多行,而且格式也比较*。不过,和 Header 里的一样,它也要以动词开头,使用现在时。此外,它还必须要包括修改的动机,以及和跟上一版本相比的改动点。

Footer 主要用来说明本次 commit 导致的后果。在实际应用中,Footer 通常用来说明不兼容的改动和关闭的 Issue/bug 列表,关闭的 Bug 需要在 Footer 部分新建一行,并以 Closes 开头列出,例如:Closes #123。如果关闭了多个 Issue,可以这样列出:Closes #123, #432, #886。

以下是一个完整的提交


refactor(elements): remove unneeded Custom Elements polyfill from doc…

In PR #43975, the `Angular Elements` guide was updated to remove
mentions of the Custom Elements-related polyfills, since they are no
longer necessary in v13+ (due to all CLI projects being ES2015+ and all
supported browsers natively supporting Custom Elements).

This commit updates the related docs example boilerplate to not include
the unneeded `@webcomponents/custom-elements` polyfill.

Close #44214


总结

在项目开发中,好的 Commit Message 可以起到以下几点好处。

  1. 可以使自己或者其他开发人员能够清晰地知道每个 commit 的变更内容,方便快速浏览变更历史,比如可以直接略过文档类型或者格式化类型的代码变更。
  2. 可以基于这些 Commit Message 进行过滤查找。
  3. 可以基于规范化的 Commit Message 生成 Change Log。
  4. 可以依据某些类型的 Commit Message 触发构建或者发布流程,比如当 type 类型为 feat、fix 时我们才触发 CI/CD 流程。
上一篇:我的注释那去了?


下一篇:【狂神说Spring】实验-IOC-XML配置