angular代码规范_Angular 工具篇之规范化Git版本管理

邹山
2023-12-01

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[optional scope]:

[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

2

3feat: allow provided config object to extend other configs

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

2

3

4

5fix: 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

接着在命令行输入以下命令:1echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

运行以上命令后项目会生成 commitlint.config.js。当然我们也可以手动创建 commitlint.config.js 文件,然后在文件内输入以下内容:1module.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 是否生效:不符合规范的 commit message1$ git commit -m "foo: this will fail"

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

2

3

4

5

6

7husky > 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)符合规范的 commit message1$git commit -m "chore: lint on commitmsg"

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

2

3

4

5usky > 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 这款工具。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 设定前缀:1$npm run release -- --prerelease alpha

此时,当前版本将变为 1.0.1-alpha.0。除了 --first-release 和 --prerelease 标识外,standard-version 还支持一个很有用的标志 --release-as,它支持三种不同的参数: major, minor 或 patch,使用方式如下: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"

}

参考资源

 类似资料: