我们平时在多人协同开发的时候,经常会需要在版本发布之前手动去维护
CHANGELOG
文件。但如果开发过程没有规范commit
提交的话,在维护CHANGELOG
的时候也是很容易遗漏一些特性的,而且手动维护CHANGELOG
文件也是比较繁琐的。因此就需要引入commit message
规范来提升代码的维护效率及如何自动生成CHANGELOG
文件。
本篇文章介绍的是 Angular 规范,这是目前使用最广的写法,比较合理和系统化,并且有配套的工具。如果需要定制 CHANGELOG
内容风格,可以参考另一篇文章 # Git Commit 规范及 CHANGELOG 定制生成 。
Commit Message 规范格式
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
Header
type(必填)
# 主要 type
feat: 增加新功能
fix: 修复 bug
# 特殊type
docs: 只改动了文档相关的内容
style: 不影响代码含义的改动,例如去掉空格、改变缩进、增删分号
build: 构造工具的或者外部依赖的改动,例如 webpack,npm
refactor: 代码重构时使用
revert: 执行 git revert 打印的 message
# 暂不使用type
test: 添加测试或者修改现有测试
perf: 提高性能的改动
ci: 与 CI(持续集成服务)有关的改动
chore: 不修改 src 或者 test 的其余修改,例如构建过程或辅助工具的变动
scope(非必填)
scope
用于说明 commit
影响的范围,比如数据层、控制层、视图层等等,视实际使用情况而定
subject(必填)
subject
用于说明 commit
目的的简短描述,不超过50个字符
Body
body
用于说明 commit
的详细描述,内容可以分成多行,主要描述改动之前的情况及修改动机,对于小的修改不作要求,但是重大需求、更新等尽量添加 body 来作说明
Footer
break changes
break changes
用于说明是否产生了破坏性修改(不兼容变动),涉及 break changes
的改动必须指明该项,类似版本升级、接口参数减少、接口删除、迁移等。
affect issues
affect issues
用于说明是否影响了某个 issue
。
注: 下面的
commitizen + cz-conventional-changelog
可以在提交的时候使用git cz
命令会自动显示对应的commit
规范信息提示
Commitizen(规范 commit 命令行工具)
安装
npm install -g commitizen
cz-conventional-changelog
使用方式(二者选其一即可)
- 全局安装使用
npm install -g cz-conventional-changelog
全局模式下,需要 ~/.czrc
配置文件, 为 commitizen
指定 Adapter
。
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
- 项目中使用
运行下面的命令,使其支持
Angular
的Commit Message
格式
commitizen init cz-conventional-changelog --save --save-exact
注意⚠️:已经通过全局方式配置的话!输入上面命令会报错(如下图)
解决:如果还是想要在项目中配置,可以按提示添加 --force
强制覆盖全局配置
commitizen init cz-conventional-changelog --save --save-exact --force
输入上面命令后在项目根目录 package.json
文件内 会自动生成 配置信息并安装 cz-conventional-changelog
"devDependencies": {
"cz-conventional-changelog": "^3.3.0"
},
"config": {
"commitizen": {
"path": "./node_modules/cz-conventional-changelog"
}
}
commit 提交
commit
的时候使用 git cz
就可以根据生成自动化的提示 commit message
进行选择操作了
git cz
进入 interactive
模式,根据提示依次填写
1. Select the type of change that you're committing 选择改动类型 (<type>)
2. What is the scope of this change (e.g. component or file name)? 填写改动范围 (<scope>)
3. Write a short, imperative tense description of the change: 写一个精简的描述 (<subject>)
4. Provide a longer description of the change: (press enter to skip) 对于改动写一段长描述 (<body>)
5. Are there any breaking changes? (y/n) 是破坏性修改吗?默认 n (<footer>)
6. Does this change affect any openreve issues? (y/n) 改动修复了哪个问题?默认 n (<footer>)
Commitlint & Husky(规范 commit message 验证)
commitlint
: 用于检查提交信息;husky
是hook
工具,作用于git-commit
和git-push
阶段
依赖安装
npm i husky @commitlint/config-conventional @commitlint/cli -D
配置信息
commitlint 配置
根目录下新建 commitlint.config.js
配置文件,也可以在 package.json
文件内配置(二者选其一)
commitlint.config.js 文件
rules
也可以不添加使用默认的 rules
配置
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'body-leading-blank': [2, 'always'], // body 开始于空白行
'header-max-length': [2, 'always', 72], // header 字符最大长度为 72
'subject-full-stop': [0, 'never'], // subject 结尾不加 '.'
'type-empty': [2, 'never'], // type 不为空
'type-enum': [2, 'always', [
'feat', // 新特性、需求
'fix', // bug 修复
'docs', // 文档内容改动
'style', // 不影响代码含义的改动,例如去掉空格、改变缩进、增删分号
'refactor', // 代码重构
'test', // 添加或修改测试
'chore', // 不修改 src 或者 test 的其余修改,例如构建过程或辅助工具的变动
'revert', // 执行 git revert 打印的 message
]],
}
};
package.json 文件
{
"commitlint": {
"extends": ["@commitlint/config-conventional"]
}
}
husky 配置
旧 husky
配置,我试了下好像没啥效果, 可以使用下面新的配置
package.json 文件
{
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
}
新的 husky
配置
Active Hooks
执行下面命令会生成一个 .husky
文件夹
npx husky install
Add Hooks
向 .husky
文件那添加内容
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'
Conventional-changelog-cli (自动生成 CHANGELOG 文件信息)
安装
npm install -g conventional-changelog-cli
命令配置与执行
将命令配置到 package.json
文件 script
中
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}
}
执行 npm run changelog
,可以自动生成 CHANGELOG.md
文件
npm run changelog
注:在每次执行
npm run changelog
命令自动生成CHANGELOG.md
, 之前需要按SemVer
规范 更新版本。 否则,会导致增量生成的CHANGELOG
一直都有之前的commit
记录。
参考文章:
commitlint 官网
Git Guide
Commit message 和 Change log 编写指南
Git commit message 规范
规范你的 commit message 并且根据 commit 自动生成 CHANGELOG.md