qrcode

马上订阅,开启修仙之旅

Angular 工具篇之规范化Git版本管理

Angular 工具篇系列教程目录:

目前很多的项目都已经使用 Git 作为版本控制工具,使用 Git 意味着我们每天都要与 Git Commit Message 打交道。Git Commit Message 看似简单,但实际却很重要。通过 Git Commit Message 我们可以快速地了解本次提交的信息,比如解决了哪个 Bug、优化了什么问题或新增了什么功能等。

俗话说得好,无规矩不成方圆。因为 Git Commit Message 很重要,所以为了能够更好地进行项目开发与维护,我们就需要规范化 Git Commit Message,除此之外,规范化 Git Commit Message 还有以下的好处,比如:

  • 自动化生成 CHANGELOG。
  • 基于提交的类型,自动决定语义化的版本变更。
  • 向同事、公众与其他利益关系人传达变化的性质。
  • 触发构建和部署流程。
  • 让人们更容易地探索结构化的提交历史,降低贡献项目的难度。

那么应该如何规范化 Git Commit Message,这里我们可以使用开源社区为我们总结出了一套名为 Conventional Commits 的书写规范,该规范受到了 Angular Commit Guidelines 的启发,并在很大程度上以其为依据。它规定的格式如下:

1
2
3
4
5
<type>[optional scope]: <description>

[optional body]

[optional footer]

type 用于表示此次改动的类型,目前常用的主要有以下几种:

  • feat 新功能(feature)表示在代码库中新增了一个功能(这和语义化版本中的 MINOR 相对应)

  • fix 表示在代码库中修复了一个 bug(这和语义化版本中的 PATCH 相对应)

  • docs 文档(documentation)

  • style (格式化, 缺失分号等; 不包括生产代码变动)

  • refactor (重构代码)

  • perf (性能优化)

  • test (添加缺失的测试, 重构测试, 不包括生产代码变动)

  • chore (更新grunt任务等; 不包括生产代码变动)

scope:一个可选的修改范围,用于标识此次提交主要涉及到代码中哪个模块。

description:简明扼要描述本次提交的内容,首字母无需大写,结尾不需要使用 .

optional body:详细描述本次提交,比如此次变更的动机,如需换行,则使用 |

optional footer:描述与之关联的 issue 或 break change。

Conventional Commits 示例

  1. 包含了描述与正文内破坏性变更的提交说明
1
2
3
feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
  1. 不包含正文的提交说明
1
docs: correct spelling of CHANGELOG
  1. 包含作用域的提交说明
1
feat(lang): added polish language
  1. 为 fix 编写的提交说明,包含可选的 issue 编号
1
2
3
4
5
fix: minor typos in code

see the issue for details on the typos fixed

fixes issue #12

现在 Git Commit Message 规范已经找到了,但仅仅靠规范还是不能保证项目中的每个成员都遵循规范。这时我们还需要一个工具,能够智能地检测我们的 commit message 是否符合规范的要求。值得庆幸的是,现在已经有现成的工具了,它就是 commitlint,接下来我们来介绍在项目中如何使用 commitlint

commitlint 项目实战

首先我们要先安装 commitlint 以及 conventional 规范:

1
2
3
4
# Install commitlint cli and angular config
$ npm install --save-dev @commitlint/{config-conventional,cli}
# For Windows:
$ npm install --save-dev @commitlint/config-conventional @commitlint/cli

接着在命令行输入以下命令:

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

运行以上命令后项目会生成 commitlint.config.js。当然我们也可以手动创建 commitlint.config.js 文件,然后在文件内输入以下内容:

1
module.exports = {extends: ['@commitlint/config-conventional']}

现在我们已经完成了 commitlint 的配置,但我们还需要在每次提交时,自动触发 commitlint 进行规范检查。要实现这个功能,我们可以借助另一个工具 husky

🐶 Git hooks made easy

Husky can prevent bad git commit, git push and more 🐶 woof!

husky 是一个增强的 git hooks 工具,它让我们可以在 git hook 的各个阶段运行 package.json 中设定的任务。

下面我们继续来安装 husky:

1
$ npm install --save-dev husky

安装完成后,我们需要在 package.json 文件中添加以下的配置项:

1
2
3
4
5
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}

完成上述的配置后,我们可以验证一下 commitlint 是否生效:

  1. 不符合规范的 commit message
1
$ git commit -m "foo: this will fail"

以上命令运行后,会输出以下信息:

1
2
3
4
5
6
7
husky > commit-msg (node v9.11.0)
⧗ input:
foo: this will fail

✖ type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
✖ found 1 problems, 0 warnings
husky > commit-msg hook failed (add --no-verify to bypass)
  1. 符合规范的 commit message
1
$ git commit -m "chore: lint on commitmsg"

以上命令运行后,会输出以下信息:

1
2
3
4
5
usky > commit-msg (node v9.11.0)
⧗ input: chore: lint on commitmsg
✔ found 0 problems, 0 warnings

[master 394dce6] chore: lint on commitmsg

如果我们项目的 Git Commit Message 严格遵守 conventional 规范,那么在发布版本时,我们就可以自动生成 CHANGELOG,这里我们可以使用的是 standard-version 这款工具。

🏆 Replacement for npm version with automatic CHANGELOG generation

顾名思义,standard-version 用于替代 npm version,同时还能自动生成 CHANGELOG。最后,我们来简单介绍一下 standard-version 这款工具。

standard-version 简介

在介绍 standard-version 之前,我们先来简单了解一下 Semver(Semantic Versioning) 规范,该规范规定了版本号如何表示,如何增加,如何进行比较,不同的版本号意味着什么。

版本格式:主版本号.次版本号.修订号,版本号递增规则如下:

  • 主版本号(major):当你做了不兼容的 API 修改。
  • 次版本号(minor):当你做了向下兼容的功能性新增,可以理解为 Feature 版本。
  • 修订号(patch):当你做了向下兼容的问题修正,可以理解为 Bug fix 版本。

先行版本号及版本编译信息可以加到 “主版本号.次版本号.修订号” 的后面,作为延伸。Semver 规范中使用alpha、beta、rc 来修饰即将要发布的版本。它们的含义是:

  • alpha:内部版本。
  • beta:公测版本。
  • rc:即 Release Candiate,正式版本的候选版本。

在发布 npm 包时,为了让我们更好的遵从 Semver 规范,npm 为我们提供了 npm version 命令,具体使用方式如下:

  • 升级补丁版本号:npm version patch。
  • 升级小版本号:npm version minor。
  • 升级大版本号:npm version major。

关于 Semver(语义化版本号) 的相关内容,这里我们不再详细展开。感兴趣的同学,可以阅读 腾讯IVWEB团队 发布的 Semver(语义化版本号)扫盲 这篇文章。接下来我们开始介绍 standard-version 这款工具。

首先以 local 模式安装 standard-version

1
$ npm install --save-dev standard-version

然后在 package.json 的 scripts 中添加以下配置:

1
2
3
4
5
{
"scripts": {
"release": "standard-version"
}
}

若需要发布首个版本,则可以运行以下命令:

1
$ npm run release -- --first-release

如果需要发布预发布版本,则可以使用 --prerelease 标志,比如:

1
$ npm run release -- --prerelease

假设你当前最新的版本是 v1.0.0,在运行上述命令后,你的版本将变为 v1.0.1-0。此外,如果你的预发布版本要包含 alpha 前缀,你可以通过 --prerelease <name> 设定前缀:

1
$ npm run release -- --prerelease alpha

此时,当前版本将变为 1.0.1-alpha.0。除了 --first-release--prerelease 标识外,standard-version 还支持一个很有用的标志 --release-as,它支持三种不同的参数: major, minorpatch,使用方式如下:

1
$ npm run release -- --release-as minor

为了方便地进行版本发布,我们也可以在 npm scripts 中定义对应的任务,比如:

1
2
3
4
{
"release:minor": "standard-version --release-as minor && git push --follow-tags origin master",
"release:major": "standard-version --release-as major && git push --follow-tags origin master"
}

参考资源


欢迎小伙伴们订阅前端修仙之路,及时阅读 Angular、RxJS、TypeScript 和 Node.js 最新文章。

qrcode