Git 提交规范

最近发现团队有些新人有个坏毛病,就是 git 提交信息全是 ok,用 sourcetree 一看,整整齐齐全是 ok,压根都不知道每次提交解决了什么问题。

git-ok

既然新人不讲码德,那我在此也劝这些新人耗子尾汁,记住:

ok 提交一时爽,git 回滚火葬场

在一个团队当中,既然大家维护同一个仓库,就要遵循相应工作流程和提交规范,其中 commit message 是比较重要的一个点,一个可读性好、描述清晰的 commit message,可以让团队其他成员不必深入看代码即可了解这次提交的作用。

更为重要的时,规范提交信息之后,就可以直接从 commit 生成 changelog(即发布新版本时,用来说明与上一个版本差异的文档),这就节省了一大笔时间。

国内外比较认同的就是 Angular 的提交规范,简单且清晰,只有三个部分:标题区、内容区和备注区。因此要求团队新人完全遵守该规范:

1
2
3
4
5
<类型>(<改动范围>): <精简总结>
// 空一行
<详细描述>
// 空一行
<备注>

其中类型精简总结这两个是必填的,其余都是选填。接下来详细讲解每一部分应该写什么内容:

标题区

标题行的格式为:

1
<类型>(<改动范围>): <精简总结>

示例提交:

1
2
3
test(compiler): use `yarn bazel` instead of `bazel` in error message
docs(router): Correct equivalent for 'enabled' initial navigation
fix(language-service): Prevent matching nodes after finding a keySpan

这些示例都是从 Angular 官方提交中截取出来的,可以看到完全遵循标题行约定的格式,其中:

<类型> 是必填项,只能是下面几种之一:

  • feat: 新功能
  • fix: 修复bug
  • docs: 只改动了文档
  • style: 修改代码格式(例如去掉空格、改变缩进、增删分号,不影响代码逻辑)
  • refactor: 重构代码(理论上不影响现有功能)
  • perf: 提升性能的改动
  • test: 增加修改测试用例
  • chore: 改变构建流程、或者增加依赖库、工具等
  • revert: 回滚到上一个版本

其中最常用的就是 feat 和 fix 这两个了,这两类提交的占比一般超过50%。

(<改动范围>) 这个不是必填的,当项目划分为捞几个模块的时候,最好指定改动的模块,例如上面 Angular 提交案例中的 compiler(编译器)和 router(路由)两个模块。

<精简总结> 这个也是必填的,而且非常重要!为什么叫精简总结呢,意思是文字不能太多,绝对不能超过 50 个字符,并且是总结和概括性的文字,例如:

1
2
feat: 支持bigsur系统
fix: 修复win7闪退问题

一定要让人一眼就能看出来本次提交到底添加了什么功能或解决了什么问题,这些信息可直接用于 changelog。

内容区

这是对本次 commit 的详细描述,可以分成多行,下面是一个简单的示例:

1
2
3
4
fix: 修复入场不能自动释放的bug

增加定时任务,每天凌晨跑一次
自动离场时忽略未支付订单

在内容区是可以写很多行的,而且可以描述得非常详细,例如:

1
2
3
4
5
6
7
perf: 在渲染时使用新的diff算法来减少Vue组件更新引起的Page.setData的实际更新量

1、core/observer的set方法中,监听对象更新值时,把更新的key值绑定在vm数据对象上
2、每次真实调用setData前,用 runtime/diffData.js 进行检查优化大小,规则为:
A.第一次vm渲染到小程序上,全量更新,并记下标志
B.第二次以后更新,检查_data对象,如果有__keyPath,跟据__keyPath更新,没有__keyPath表示没有更新
3、使用效果:减少了只改动一个根节点属性却造成整个组件树的数据都传递给Page.setData的情况,从而减少因为setData量大引起的真机尤其安卓卡顿的情况

这样的好处就是,如果团队其他成员如果对本次提交感兴趣,可以通过阅读内容区的详细描述来获取更多提交信息。

因此,我们要求新人:对于一些小的修改,此部分不作要求,但是重大需求、更新等必须添加 body 来作说明。

备注区

此部分只用于如下三种情况:

  1. 产生了破坏性修改,即:BREAKING CHANGE
1
2
3
perf(core): improve vdom diffing by removing 'foo' option

BREAKING CHANGE: The 'foo' option has been removed.
  1. 关闭某个 issue
1
2
3
fix(v-model): handle events on blur

close #28
  1. revert 某次提交
1
2
3
revert: feat(compiler): add 'comments' option

This reverts commit 50c4d4bc92ac861c9be435965a3ae493779e527c.