你见过最奇葩的代码提交信息是什么？别再为写commit message头疼了！

于是乎_
4,971 阅读7分钟

写在前面

对一个developer来说，有时候变量命名，提交代码时的提交信息会让人很头疼，本文主要聊聊怎么优雅的书写commit message。

你见过最奇葩的代码提交信息是什么？

曾在上家公司的一个项目中，见过我至今以来见过最奇葩的代码提交信息，让我至今难忘。那个项目的前三个commit记录的提交信息分别是：

First Blood

Double kill

Triple kill

简直让人啼笑皆非，不知道那位仁兄是不是在一边写代码一边开黑。你是否也见过什么样的奇葩的commit message呢？！

这样的提交信息，不仅无法告知其他人之前提交了什么内容，而且会让觉得很不认真很不专业。

那规范的commitmessage能给我们带来哪些好处呢？

规范commit message的好处

  1. 可读性好，根据commit信息就能明确知道本次提交的修改内容及影响范围

  2. 可以根据不同的提交类型，过滤掉不想关注的提交，提高效率

  3. 可以自动化生成changeLog，甚至可以自动更新语义话的版本

  4. 可以降低codereview的沟通成本

  5. 一份清晰规范的commit messge，可以让你表现的更专业

那么什么样的commit message才算是好的呢？我们来看看在业界被很多人认同的两种提交风格。

Angular规范

Angular 的commit信息由标题，正文和页脚三个部分组成，每个部分中间通过空行分隔。标题部分包括类型，范围和主题三个部分。

<type>(<scope>): <subject><BLANK LINE>
<body>
<BLANK LINE><footer>

type 提交类型

提交的类型必须是下面的一个：

feat：增加一个新功能

fix：修复bug

docs：只修改了文档

style：做了不影响代码含义的修改，空格、格式化、缺少分号等等

refactor：进行代码重构，既不是修复bug，也不是新功能的修改

perf：改进性能的代码

test：增加测试或更新已有的测试

chore：构建或辅助工具或依赖库的更新

scope 范围

说明当前提交的代码影响的范围，如果当前更改影响的不止一个范围时，可以使用*

subject 描述

包含对变更的简洁描述: 使用祈使句，现在时态:"change"而不是"changed"或"changes"，第一个字母不要大写, 末尾没有点(.)

body 正文

使用祈使句，body应该包括为什么修改，具体修改了哪些了东西。

footer 页脚注释

用来放置 Breaking Changes 或 Closed Issues

Conventional Commits 规范

基于Angular的提交规范衍生出的规范，很大程度上以其为Augular的规范为依据 提交格式与Augular基本一致

<type>[optional scope]: <description>
[optional body]
[optional footer]

type 提交类型

类型是必须提供的，且必须是名词，其后接一个可选的作用域字段，以及一个必要的冒号（英文半角）和空格；

  • 提交新功能或新特性时，必须使用feat类型；
  • 修复了 bug 时，必须使用fix类型；
  • 可以使用 feat 和 fix 之外的类型;

scope 范围

作用域必须是一个描述某部分代码的名词，并使用圆括号

description 描述

描述是必须项，字段必须紧接在类型/作用域的空格之后。描述指的是对代码变更的简短总结

body 正文

正文可可选的，如果书写必须起始于描述字段结束的一个空行后

footer

正文结束的一个空行之后，可以编写一行或多行脚注

BREAKING CHANGE

不兼容更新必须标示在正文区域最开始，或脚注区域中某一行的开始，必须包含大写的文本BREAKING CHANGE，后面紧跟冒号和空格。

在 BREAKING CHANGE: 之后必须提供描述，以描述对 API 的变更。例如：BREAKING CHANGE: environment variables now take precedence over config files.

可以在类型/作用域前缀之后，: 之前，附加 ! 字符，以进一步提醒注意不兼容变更。当有 ! 前缀时，正文或脚注内必须包含 BREAKING CHANGE: description

Conventional Commits规范是和SemVer规范（语义化版本）的约定是吻合的。

SemVer 是一套语义化版本控制的约定，定义的格式为 ** X.Y.Z（主版本号.次版本号.修订号）** ：

X.主版本号：进行不向下兼容的修改时，递增主版本号

Y.次版本号: 做了向下兼容的新增功能或修改

Z.修订号：做了向下兼容的问题修复

Conventional Commits规范是和SemVer规范相吻合的目的是什么呢？！ 我们可以根据commit的类型去自动化的生成语义化的版本。

我们比较熟知 electron 项目就采用了Conventional Commits规范，其他采用了这套规范的开源项目还有：

  • yargs：广受欢迎的命令行参数解析器。
  • istanbuljs：一套为 JavaScript 测试生成测试覆盖率的开源工具和类库。
  • uPortal-home 和 uPortal-application-framework：用于增强 Apereo uPortal 的可选用户界面。
  • massive.js：一个用于 Node 和 PostgreSQL 的数据访问类库。
  • scroll-utility：一个居中元素和平滑动画的滚屏工具包实例。
  • Blaze UI：无框架开源 UI 套件。
  • Monica：一个开源的人际关系管理系统。

相关工具

有了规范是好事，但不想记那么多的type怎么办？又怎么保证团队每个成员真的按照规范去执行呢？这些都可以通过工具来解决。

Commitizen

一款帮助我们按照规则去提交提交代码的懒人工具，它是一个通用的工具，提供了多种commit Message风格可以选择，比如我们上面提到的Conventional规范，就可以通过按照 cz-conventional-changelog 来实现。

除了提供了一些可选的风格，还支持根据已有的规范去更改创建一套属于自己团队的风格配置。

安装：

npm install commitizen -g

选择风格：

commitizen init cz-conventional-changelog --save-dev --save-exact

or

commitizen init cz-conventional-changelog --yarn --dev --exact

提交代码时，使用git cz 代替 git commit，每一步都会有提示，保证按照规范提交。

commitlint

commit message 的 linter，用来对 message 进行检查，防止提交了不符合规范的提交信息。

可以结合 git hooks 在提交commit时进行自动检查，不符合规范的commit不允许提交。

同样的，commitlint也支持配置安装不同风格的配置，同时，你也能够发布并使用自己的配置。

安装：

npm install --save-dev @commitlint/{config-conventional,cli}

配置风格

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

结合git hooks使用

先安装husky

npm install --save-dev husky

package.json中增加配置

{
"husky":{
  "hooks": {"commit-msg": "commitlint -E HUSKY_GIT_PARAMS" }       
   }
}

这样在输入不符合风格的commit Message会无法通过，并会给出具体的提示。

standard-version

standard-version需要使用Conventional Commits规范，能够帮助自动生成符合SemVer规范的版本和 CHANGELOG。

安装：

npm i --save-dev standard-version

package.json中增加配置：

{"scripts": {"release": "standard-version" }}

第一次发布版本，执行命令，同时生成changeLog

npm run release -- --first-release

之后版本变更，直接执行

npm run release

常见问题

一次提交多种类型怎么操作

尽可能拆分的task，每完成一部分就进行一次提交，避免一次提交过多的代码。这样能够避免一次commit修改过多文件，导致后续的维护，回退等的困难。

如果真的有这样的提交，可以选择最重要改动的type，在body部分详细写明具体的改动。

提交了不规范的信息怎么处理

如果使用了Commitizen或commitlint，基本上可以保证提交符合规范的Message，但是也可能出现选错了类型的问题，比如是新增的功能，但是一手抖，选成了fix并完成了commit，这时可以使用 git rebase -i 来编辑提交历史。

参考

Angular规范：github.com/angular/ang…

Conventional Commits 规范： www.conventionalcommits.org/en/v1.0.0-b…

SemVer规范： semver.org/

欢迎关注我的公众号「前端小苑」，我会定期在上面更新原创文章。

avatar
文章
阅读
粉丝