一、 什么是语义化的提交信息?
「语义化的提交信息」这一概念来自于 conventionalcommits.org ,被称为「约定式提交」。
约定式提交的优点有:
- 可以创建清晰的提交历史
- 使基于规范的自动化工具变得更加容易:如自动生成CHANGELOG
- 减少bug、提高效率
- 更加专业
约定式提交按照一种固定的模式就行书写,这样不仅有利于团队协作,还可以在项目后期通过自动化的方式生成一些文档。常见的公式如下所述。
公式
<类型>[可选的作用域]: <描述>
// 这里空一行
[可选的正文]
// 这里空一行
[可选的脚注]
描述是用于 git commit -m <message> 中 message 的格式。
scope作用域是非必填的:用于说明commit的影响范围,
比如一般分层项目的哪一层:数据层、业务逻辑层还是视图层,视项目不同而不同。
subject 是 commit目的的简短描述:
- 一般以动词开头
- 首字母小写
- 结尾不加句号
类型用于说明commit的类别,类型必填的
其中类型字段可以是下列选项中的一个:
- feat: 表示新增的一个功能feature
- fix: 表示该提交修复了一个bug
- docs: 表示修改了文档
- style: 表示修改了样式
- refactor: 表示进行了代码重构
- test: 表示进行了测试相关的工作
- perf: 表示性能优化工作
- chore: 琐事、杂项。不知道如何归类的就叫这个吧 :-)(chore这个单词本意是日常事务,乏味无聊的工作),指构建过程或者辅助工具的代码或配置变动
举个例子:
feat: add hat wobble
^--^ ^------------^
| |
| +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.
更多例子:
chore: add Oyster build script
docs: explain hat wobble
feat: add beta sequence
// 包含了可选的作用域
feat(lang): add polish language
fix: remove broken confirmation message
// 为 fix 编写的提交说明,包含(可选的) issue 编号
fix: correct minor typos in code
see the issue for details on the typos fixed
closes issue #12
refactor: share logic between 4d3d3d3 and flarhgunnstow
style: convert tabs to spaces
test: ensure Tayne retains clothing
看下 vue.js 仓库的 commits 列表里截一张图,
会发现这种规范的commit管理方式看起来不仅专业,
而且有利于开源参与者理解每一条commit的意义。
更多详情可以参考文章:Commit message 和 Change log 编写指南
二、 自动lint git commit 消息
那么问题来了,如果有一个项目,从始至终都是你一个人在维护,那么你想怎么写都可以,没有人会干预你,但是如果是一个多人维护的项目,大家都有各自的想法,连「每行代码结尾是不是要加分号」这种的很难统一的行为,更何况是提交代码呢?
所以我们需要一个可以校验提交信息格式的工具:commitlint
安装
# 安装依赖
npm i husky lint-staged prettier @commitlint/cli @commitlint/config-conventional -D
配置
package.json中的相关配置:
"husky": {
"hooks": {
"pre-commit": "npm run lint-staged",
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
},
"lint-staged": {
"*.js": [
"npm run prettier"
]
},
其中"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"这行表示当执行git commit时会使用 commitlint进行格式校验,
格式来自于配置文件:commitlint.config.js:
module.exports = {
extends: ["@commitlint/config-conventional"],
};
执行成功如图所示
三、自动生成 CHANGELOG.md 文件
如果你要开发一个对外的项目或工具,最好在仓库中提供一个CHANGELOG.md文件,供使用者查看项目的变更历史,有助于使用者更加了解你的项目。
原理
引用一句话:
Generate a changelog from git metadata
该工具是基于git commit 的提交信息生成的 chagelog 文件。
目前社区里用的比较多的是 angular提交规范
如何使用自动化的方式生成changelog文件,而不是项目作者手动维护呢?
推荐使用conventional-changelog这个npm包,一条命令就可以自动生成好项目变更历史文件。
安装
项目源码在github上,感兴趣的可以去看一看。
# 安装
$ npm install -g conventional-changelog-cli
安装成功以后可以看一下这个命令行工具的帮助文档:
# 查看帮助
$ npx conventional-changelog --help
所以我们可以通过如下命令,便捷的生成变更历史记录:
# 生成 CHANGELOG.md 文件
$ conventional-changelog -p angular -u -i CHANGELOG.md -s -r 0
命令太长记不住怎么办? 放到npm scripts中:
// package.json
scripts: {
"changelog": "conventional-changelog -p angular -u -i CHANGELOG.md -s -r 0"
}
以后只需要在命令行执行npm run changelog就可以了。
还有很多有趣又有用的功能等着大家去探索,有什么问题欢迎大家评论区留言。