前言

为了便于团队的协同开发，我们在git commit时，需要有一个统一的格式。

commit 规范

<type>(<scope>): <subject> // 必填, 描述主要修改类型和内容。注意冒号后面有空格
<BLANK LINE>
<body> // 描述为什么修改, 做了什么样的修改, 以及开发的思路等等
<BLANK LINE>
<footer> // 放 Breaking Changes 或 Closed Issues

type，必填，commit的类型，主要包含下面几种：
- feat，新功能
- fix，修复bug
- refactor，重构
- style，格式修改
- docs，文档修改
- build，构建流程或依赖管理等修复
- ci，ci相关的修改
- test，测试用例修改
- perf，性能提升
- revert，回滚
scope，选填，commit 影响的范围, 比如: route, component, utils, build...
subject，必填，commit的简短描述，格式可以参考50/72 formatting
body，选填，commit的具体修改内容, 可以分为多行
footer，选填，备注信息，通常是Breaking Changes或 Closed Issues

commitlint

我们介绍了commit的规则，但是需要一个工具来校验是否我们的commit是否符合该规则，这里我们使用commitlint来达到这个目的。

下载

npm install -s @commitlint/cli @commitlint/config-angular

@commitlint/config-angular主要用于生成commit校验规则，也可以使用@commitlint/config-conventional(支持type类型为chore)。

配置文件

在下载完npm包后，我们需要生成配置文件commitlint.config.js。

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

可以使用上面的命令生成文件，也可以直接创建该文件。

module.exports = {
  extends: ['@commitlint/config-angular'],
};

配置规则

@commitlint/config-angular会自带默认规则，我们也可以通过rules自己配置符合我们项目的规则。下面是一些常用的配置，项目内容可以看这里。

module.exports = {
  extends: ['@commitlint/config-angular'],
  rules: {
    'type-enum': [ // type的可选类型
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert'],
    ],
    'type-case': [2, 'always', 'lowerCase'], // type需小写
    'type-empty': [2, 'never'], // type不能为空
    'subject-full-stop': [2, 'never', '.'], // subject不以‘.’结尾
  },
};

rules中的规则写法为docs/rules。

第一个参数(0|1|2)，0表示禁止，1表示警告，2表示错误
第二个参数(always|never)，never表示反转该规则
第三个参数，表示用于此规则的值

git hook

作为能用工具就使用工具的原则，我们可以结合git hook来进行commit的检查。这里我们需要配合husky来使用。

在husky已经安装完毕的情况下，我们添加commit-msg信息。

// package.json
"husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
},

这样配置完毕后，在提交commit的时候就会自己检查commit规则，若未通过会有类似下面的提示：

ℹ No staged files match any configured task.
husky > commit-msg (node v14.12.0)
⧗   input: chore123: test
✖   type must be one of [feat, fix, docs, style, refactor, test, revert] [type-enum]

上面我们了解了关于commit的规则以及相关校验，但是我们是否可以往前一步，通过工具来提示或者直接生成commit呢？

commit 模板

我们通过设置commit模板，在git commit时带出模板信息，即可按照规则编辑commit信息。

首先，在根目录中添加.gitmessage文件。

# head:
# <type>(<scope>): <subject>
# - type: feat, fix, docs, style, refactor, test, build, ci, revert
# - scope: can be empty (eg. if the change is a global or difficult to assign to a single component)
# - subject: start with verb (such as 'change'), 50-character line
#
# body:
# 72-character wrapped. This should answer:
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# footer: 
# - Include a link to the ticket, if any.
# - BREAKING CHANGE
#

再添加到git配置中：

// 项目安装
git config commit.template '.gitmessage'

// 全局安装
git config --global commit.template '.gitmessage'

那么，当我们修改了文件，执行了git add，再执行git commit(若修改的多个文件，需要执行git add .和git commit -a)，这时会显示模板信息。

我们仅需要在vim带出的模板中进行commit信息编辑，保存后即可正常提交commit信息。

注：模板中需要提交的commit信息前不能有#。

commitizen

除了git commit模板，我们也可以通过commitizen来自动生成满足规则的commit信息。

下载

npm install -s commitizen cz-conventional-changelog

cz-conventional-changelog是commitizen的Adapter，满足Angular团队的commit规范。

配置

我们在使用npm脚本来控制commitizen:

// package.json
"script": {
    "commit": "cz",
},

接着，需要配置cz-conventional-changelog。

// package.json
"config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
}

我们也可以在.czrc或者.cz.json文件中进行配置cz-conventional-changelog。

{
  "path": "cz-conventional-changelog"
}

命令行

执行命令行npm run commit，会提示以下信息，按照提示操作即可。

如果全局安装过commitizen, 那么可以在对应的项目中执行git cz

$ npm run commit

> cz

cz-cli@4.2.2, cz-conventional-changelog@3.3.0

? Select the type of change that you're committing: 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    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 feature 
  perf:     A code change that improves performance 
  test:     Adding missing tests or correcting existing tests 
  build:    Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)

自定义 Adapter

当然，我们也可以使用cz-customizable来自定义Adapter，用于替换cz-conventional-changelog。

// 下载
npm i -s cz-customizable

// 配置 package.json
"config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
}

同时在根目录下创建.cz-config.js文件, 维护你想要的格式。

PS: cz-customizable在项目中使用的少，感兴趣的同学可以自行研究。

changelog

我们在有了标准化的commit基础上，可以通过工具来自动生成changelog。

conventional-changelog

conventional-changelog能根据项目的commit和metadata信息自动生成 changelogs和release notes。

// 下载
npm install -s conventional-changelog-cli

// 配置 package.json
"scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
}

conventional-changelog命令行中有多个参数：

-p angular，表示commit规则标准为angular，现在有angular, atom, codemirror, ember, eslint, express, jquery 等项目的标准
-i CHANGELOG.md，表示从CHANGELOG.md读取changelog
-s 表示读写 changelog 为同一文件
-r 表示生成 changelog 所需要使用的 release 版本数量，默认为1，全部则是0。

standard-version

standard-version会根据pacakage.json中的version更新版本号，升级版本，打包tag，并更新changelog。

// 下载
npm install --save-dev standard-version

// 配置 package.json
"scripts": {
    "release": "standard-version"
}

默认情况下，standard-version会提升次版本号(minor)，我们可以通过参数(可通过standard-version --help查看全部参数)来控制。

// 当前版本v1.0.0
standard-version // output v1.1.0

// -r 指定版本
standard-version -r major // output v2.0.0
standard-version -r minor // output v1.1.0
standard-version -r patch // output v1.0.1
standard-version -r 3.0.0 // output v3.0.0

// -p 预发版本命名
standard-version -p alpha // output v1.0.0-alpha.0

// -t 版本 tag 前缀
standard-version -t stable- // output tag: stable-v1.0.0

版本说明

以上配置都是在以下版本中：

"@commitlint/cli": "^11.0.0",
"@commitlint/config-angular": "^11.0.0",
"@commitlint/config-conventional": "^11.0.0"

"commitizen": "^4.2.2",
"cz-conventional-changelog": "^3.3.0"

"conventional-changelog-cli": "^2.1.0",
"standard-version": "^9.0.0",

"husky": "^4.3.0",

node -v // v14.12.0
npm -v // 6.14.8

前端代码质量(4)-commit校验及changelog生成

前言