前端小纠结–约定式提交和自动生成changelog

约定式提交

约定式提交：每次使用git commit 的时候都需要写commit message,如果message style是按照固定的模版格式书写，对于后期的维护和编写changelog都有巨大的好处。
而且现在的很多自动生成changelog的工具，都是建立在约定式提交的基础之上。

约定式提交校验配置

约定式提交不需要任何的配置，只需要严格遵守其规范就可以了。
为了保证每次提交的commit message都是遵守conventional commit spec所以添加了校验配置.

约定式提交工具

约定式提交使用交互式提交工具（例如： commitizen），使用工具能够保证约定式提交个格式是满足规范的。

  1. 推荐使用vs code 插件commitizen

  2. 命令行方式的commitizen配置(vscode commitizen和命令行方式任选其一即可)

    1
    npm install --save-dev commitizen
1
2
3
4
5
6
// package.json配置
{
    scripts: {
        "commit": "git-cz"
    }
}
1
2
# 使用
npm run commit   # 进入交互式, 如果commit message在console中换行，请使用'开始

  1. commitizen的适配器cz-conventional-changelog

    commitizen只是一个提交的工具，只有添加了约定格式的适配器才能按照固定格式进行交互式提交，
    否则就和普通的git commit一样了。（还有其他适配器可选，请参考官方文档）
    不同的适配器，提供的约定标准有差异。

    1
    2
    # 建议安装npx这个神器 npm i npx -g
    npx commitizen init cz-conventional-changelog --save-dev --save-exact

    commitizen工具会在package.json中自动添加配置：

    1
    2
    3
    4
    5
    6
    7
    8
    {
        "config": {
            "commitizen": {
                // "path": "cz-conventional-changelog" // 全局安装模式
                "path": "./node_modules/cz-conventional-changelog"
            }
        }
    }

commitizen

约定式提交格式校验

为了防止出现不满足格式要求的commit message出现，还是需要添加上必要的格式校验.

  1. commitlint校验约定式提交格式

    commitlint是在commit message之前进行校验格式，格式不对不进行提交。

    1
    2
    # 安装
    npm install --save-dev @commitlint/config-conventional @commitlint/cli
    1
    2
    # 添加配置文件commitlint.config.js,工程根目录
    echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

  1. husky配置git hooks

    husky官网 husky配置

    有了git hooks我们可以做很多提交之前的验证。

    1
    2
    # 安装
    npm i husky --save-dev
    1
    2
    3
    4
    5
    6
    7
    8
    9
    // package.json 配置
    {
    "husky": {
        "hooks": {
          "commit-msg": "commitlint -E HUSKY_GIT_PARAMS", // 配合commitlint使用
          // "pre-commit": "lint-staged" // 配置lint-staged
        }
      }
    }

  1. lint-staged配置(可选)

    lint-staged

    list-staged主要配合linter用来格式化代码（统一的代码风格），这部是可选的。

    lint-staged是用来让格式化工具只lint需要提交的文件，其它文件忽略，这样能够提高效率。

    1
    npm i lint-staged --save-dev
1
2
3
4
5
6
7
8
9
// package.json 配置
{
    "lint-staged": {
        "src/**/*.{js,ts,css,vue,tsx,jsx}": [
            "vue-cli-service lint", // npm run lint
            "git add"
        ]
     }
}

自动生成changelog

自动生成changelog是建立在约定式提交的基础上。

自动生成changelog有两种方式：

  1. conventional-changelog-cli生成changelog

  2. standard-version生成changelog

    standard-version帮你做了自动打tag，自动生成changelog等过程.

conventional-changelog-cli配置

在约定式提交的基础上来自动生成changelog，工具类库开发，推荐直接使用standard-version，高度集成了所有东西。

1
npm install conventional-changelog-cli --save-dev
1
2
# 基本使用，其它参数参考官方网站
conventional-changelog -p angular -i CHANGELOG.md -s -r 0
1
2
3
4
5
6
// package.json配置
{
    scripts: {
        "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md",
    }
}
1
2
# 使用
npm run changelog

standard-version配置

1
2
# 安装
npm install standard-version --save-dev
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// package.json 配置
{
    "scripts": {
        "release": "standard-version"
    },
    // standard-version 好多配置看官方文档（可选）
    "standard-version": {
        // 可以配置不需要的环节
        "skip": {
           // bump, changelog, commit, tag
          "tag": true
       }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
# 项目根目录下使用，自行安装npx 模块
# npm i npx -g 
npx standard-version --release-as major
npx standard-version --release-as minor
npx standard-version --release-as patch

npx standard-version --prerelease alpha
npx standard-version --prerelease beta
npx standard-version --prerelease rc

npm run release -- -r minor
npm run release -- -p beta

package.json中的scripts命令组织

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    scripts: {
        "commit": "git-cz",
        "release": "standard-version",
         "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md",
        "release:major": "standard-version -r major -n,
        "release:minor": "standard-version -r minor -n,
        "release:patch": "standard-version -r patch -n",
        "prerelease:alpha": "standard-version -p alpha -n,
        "prerelease:beta": "standard-version -p beta -n,
        "prerelease:rc": "standard-version -p rc -n"
    }
}

参考

约定式提交规范

git commit 、CHANGELOG 和版本发布的标准自动化

Commit message 和 Change log 编写指南