文章目录
  1. 1. Commit 规范化
    1. 1.1. Angular 规范
    2. 1.2. conventional-changelog 方案
      1. 1.2.1. conventional-changelog 介绍
        1. 1.2.1.1. 支持 Conventional Changelog 的插件
        2. 1.2.1.2. Conventional Changelog 生态系统重要的模块
      2. 1.2.2. 规范 commit 命令行工具–commitizen
      3. 1.2.3. 强制执行 commit 规范–commitlint+husky
      4. 1.2.4. 自动生成 CHANGELOG–conventional-changelog-cli
      5. 1.2.5. 参考
    3. 1.3. 结束语

我们在多人协同开发的时候,经常会遇到版本打包发布时,需要手动收集更新了什么内容、修复了什么 BUG,如果日常开发中并没有养成 commit 的好习惯,我们在合入 CHANGELOG 的时候就很容易遗漏特性。本文记录前端常用的自动生成 CHANGELOG 的接入过程。

Commit 规范化

不管是哪种自动生成 CHANGELOG 的工具,基本上都依赖于每次提交 git commit 的信息。从 git commit 信息开始进行规范化,这样就可以通过工具把关键信息找出来,并自动生成到 CHANGELOG 中。

Angular 规范

目前,社区有多种 Commit message 的写法规范,这里我们使用的是 Angular 规范,这是目前使用最广的写法,比较合理和系统化,并且有配套的工具(参考《Commit message 和 Change log 编写指南》)。

每次提交,Commit message 都包括三个部分:Header(必须),Body(可省略) 和 Footer(可省略)。

1
2
3
4
5
<type, 必填>(<scope,可省略>): <subject,必填>
// 空一行
<body,可省略>
// 空一行
<footer,可省略>
  1. typetype用于说明 commit 的类别,一般来说只允许使用下面7个标识:
标识名 说明 是否会出现在 CHANGELOG 中
feat 新功能(feature)
fix 修补bug
docs 文档(documentation) 自行决定
style 格式(不影响代码运行的变动) 自行决定
refactor 重构(即不是新增功能,也不是修改bug的代码变动) 自行决定
test 增加测试 自行决定
chore 构建过程或辅助工具的变动 自行决定
  1. scopescope用于说明 commit 影响的范围,比如某个模块、某个功能。
  2. subjectsubject是 commit 目的的简短描述,不超过50个字符。
  3. bodybody部分是对本次 commit 的详细描述,可以分成多行。
  4. footerfooter部分只用于两种情况:不兼容变动、关闭 Issue。

conventional-changelog 方案

关于自动生成 CHANGELOG,社区中使用较多的则是 conventional-changelog 方案。

conventional-changelog 介绍

conventional-changelog 可以根据项目的 commit 和 metadata 信息自动生成 CHANGELOG 和 release notes的系列工具,并且在辅助 standard-version 工具的情况下,可以自动帮你完成生成version、打tag, 生成CHANGELOG等系列过程。(参考《git commit 、CHANGELOG 和版本发布的标准自动化》

支持 Conventional Changelog 的插件

Conventional Changelog 生态系统重要的模块

以上是 conventional-changelog 生态重要的几个主要模块,实际工作中这几个工具常常是配套使用的,我们也是可以根据自己的情况来挑着使用。

规范 commit 命令行工具–commitizen

一般来说,我们提供一个脚本工具给到开发者来按照指引生成符合规范的 commit 信息也是够用的,这里我们使用commitizen工具。

  1. 安装commitizen
1
npm install -g commitizen
  1. 通过以下命令来初始化项目以使用cz-conventional-changelog适配器(每个项目和构建过程都有不同的要求,因此commitizen通过适配器的方式,来保持Commitizen的扩展性):
1
commitizen init cz-conventional-changelog --save-dev --save-exact

该命令做以下三件事情:

  • 安装cz-conventional-changelog适配器npm模块
  • 将其保存到package.json的依赖项或devDependencies
  • config.commitizen配置添加到package.json的根目录,该配置告诉commitizen,当我们尝试提交此仓库时,我们实际上希望使用哪个适配器
  1. 我们可以通过执行git cz命令,来提交 git commit:
1
2
3
4
5
6
7
8
9
10
11
12
13
> git cz
cz-cli@4.0.3, cz-conventional-changelog@3.0.2
? Select the type of change that you're committing: (Use arrow keys)
> feat: A new feature
fix: A bug fix
improvement: An improvement to a current feature
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
(Move up and down to reveal more choices)

强制执行 commit 规范–commitlint+husky

使用commitizen工具,我们可以通过执行git cz命令来提交符合规范的 commit 信息,但是在日常开发中,很多小伙伴并不是通过命令行的方式来提交 commit 的,如果我们要强制校验其他人通过 vscode/webstorm 等其他工具的方式提交 commit,可以使用commitlint+husky的方式来配合使用。

  1. commitlint检查我们的 commit message 是否符合常规的提交格式,可通过以下方式安装:
1
npm install --save-dev @commitlint/config-conventional @commitlint/cli
  1. package.json中添加配置(还可以通过commitlint.config.js.commitlintrc.js.commitlintrc.json,或.commitlintrc.yml文件等方式配置),此处@commitlint/config-conventional为基于 Angular 格式的配置:
1
2
3
4
5
{
"commitlint": {
"extends": ["@commitlint/config-conventional"]
}
}
  1. husky继承了 git 下所有的钩子,在触发钩子的时候,husky可以阻止不合法的 commit、push 等等。安装husky
1
npm install husky --save-dev
  1. 使用husky添加 commit-msg 的钩子,用于检查commitlint规范:
1
2
3
4
5
6
7
{
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
}

这样,不管我们通过什么方式来提交 commit,如果 commit 信息不符合我们的规范,都会进行报错。例如我提交内容为test的 commit,会进行以下报错:

1
2
3
4
5
6
7
husky > commit-msg (node v10.16.2)
⧗ input: test
✖ subject may not be empty [subject-empty]
type may not be empty [type-empty]
✖ found 2 problems, 0 warnings
ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

自动生成 CHANGELOG–conventional-changelog-cli

如果你的所有 Commit 都符合 Angular 格式,那么发布新版本时, CHANGELOG 就可以用脚本自动生成。

  1. conventional-changelog-cli 就是生成 CHANGELOG 的工具,我们首先来安装一下:
1
npm install -g conventional-changelog-cli
  1. 通过执行以下命令,则可以生成 CHANGELOG.md 文件:
1
conventional-changelog -p angular -i CHANGELOG.md -s

我们也可以将该命令配置到scripts中,就可以通过执行npm run changelog命令来生成 CHANGELOG 了:

1
2
3
4
5
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}
}

生成的 CHANGELOG 最终样式如下:

1
2
3
4
5
# 1.0.0 (2019-11-06)
### Features
- **自动化:** 新增自动生成 CHANGELOG 相关功能 ([a9ebf7e](https://github.com/godbasin/wxapp-typescript-demo/commit/a9ebf7ee0ca53a4906ed77106b65f6d6bef92f9b))

最终的代码可参考wxapp-typescript-demo

参考

结束语


自动生成 CHANGELOG 其实是一个很好用的功能,同时其实前端自动化还会包括 CI/CD、自动化测试等功能。将一些重复性的工作进行脚本化和工具化,不正是我们程序员最擅长做的一些事情吗?

查看Github有更多内容噢:https://github.com/godbasin
更欢迎来被删的前端游乐场边撸猫边学前端噢

码生艰难,写文不易,给我家猪囤点猫粮了喵~

作者:被删

出处:https://godbasin.github.io

本文版权归作者所有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文连接,否则保留追究法律责任的权利。

文章目录
  1. 1. Commit 规范化
    1. 1.1. Angular 规范
    2. 1.2. conventional-changelog 方案
      1. 1.2.1. conventional-changelog 介绍
        1. 1.2.1.1. 支持 Conventional Changelog 的插件
        2. 1.2.1.2. Conventional Changelog 生态系统重要的模块
      2. 1.2.2. 规范 commit 命令行工具–commitizen
      3. 1.2.3. 强制执行 commit 规范–commitlint+husky
      4. 1.2.4. 自动生成 CHANGELOG–conventional-changelog-cli
      5. 1.2.5. 参考
    3. 1.3. 结束语