规范你的 commit message 而且根据 commit 自动生成 CHANGELOG.md

时间 2019-11-07

标签规范 commit message 而且根据自动生成 changelog.md changelog 繁體版

原文原文链接

项目地址： github.com/sunshine940…node

一个好的项目一般都是多人合做的结果，然而每一个人有每一个人的开发习惯，并不统一。git

因此 commit message 就显得格外的重要。有些不规范的 commit 可能过个一个月以后你本身都不知道当时的提交目的了ﾍ(;´Д｀ﾍ)，github

因此，为了能使得往后复（zhao）盘（guo）的时候更加的方便，团队之间遵照同一套 commit message 规范仍是颇有必要的。npm

本篇文章介绍的是 Angular 规范，这是目前使用最广的写法，比较合理和系统化，而且有配套的工具。json

`commit message` 的做用

提供更多的历史信息，方便快速浏览。
能够过滤某些commit（好比文档改动），便于快速查找信息。
能够直接从commit生成Change log。

`commit message` 的格式

刚刚有说到，咱们使用的是 Angular 规范，下面来大体介绍下：bash

使用 git commit 能够提交多行 commit message.ide

commit message 包括三个部分：Header，Body 和 Footer工具

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
复制代码

其中，Header 是必填，Body 和 Footer 是选填。测试

`Header`

Header 包括三个字段：type（必填）、scope（选填）和 subject（必填）优化

`type`

type 用于说明 commit 的类别，只容许使用下面 7 个标识。

feat：新功能（feature）
fix：修补bug
docs：文档（documentation）
style：格式（不影响代码运行的变更）
refactor：重构（即不是新增功能，也不是修改bug的代码变更）
test：增长测试
chore：构建过程或辅助工具的变更

type 为 feat 和 fix，则该 commit 将确定出如今 Change log 之中。

`scope`

scope 用于说明 commit 影响的范围，好比数据层、控制层、视图层等等，视项目不一样而不一样。

`subject`

subject 是 commit 目的的简短描述，不超过50个字符

以动词开头，使用第一人称如今时，好比 change，而不是 changed 或 changes
第一个字母小写
结尾不加句号（.）
复制代码

`body`

Body 部分是对本次 commit 的详细描述，能够分红多行。下面是一个范例。

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent
复制代码

`Footer`

Footer 部分只用于两种状况

不兼容变更

若是当前代码与上一个版本不兼容，则 Footer 部分以 BREAKING CHANGE 开头，后面是对变更的描述、以及变更理由和迁移方法。

关闭 Issue 若是当前 commit 针对某个 issue，那么能够在 Footer 部分关闭这个 issue

Closes #123, #245, #992
复制代码

`Commitizen` -- 自动生成合格的 `commit message`

根据上述的描述，你是否是在感慨写个 commit message 好麻烦，这里介绍下 Commitizen -- 可以根据提示自动生成符合规范的 commit message

安装

$ npm install -g commitizen
复制代码

在项目中使用

而后，在项目目录里，运行下面的命令，使其支持 Angular 的 Commit message 格式。

$ commitizen init cz-conventional-changelog --save --save-exact
复制代码

commit

在提交的时候就可使用 git cz 就能够根据提示，生成自动化的 commit message

`validate-commit-msg` 检查你的 `commit-message` 规范

Commitizen 能够帮助咱们规范本身的 commit-message，可是在团队合做中，如何规范其余成员的 commit 规范呢？

可使用 validate-commit-msg 来检查你的项目的 commit-message 是否符合格式

`validate-commit-msg` 安装

npm install --save-dev validate-commit-msg
复制代码

`husky` 安装

按照 validate-commit-msg 中 README 中写的，能够用 validate-commit-msg 做为一个 githook 来验证提交消息，而且推荐了 husky。

This provides you a binary that you can use as a githook to validate the commit message. I recommend husky. You'll want to make this part of the commit-msg githook, e.g. when using husky, add "commitmsg": "validate-commit-msg" to your npm scripts in package.json.

执行

npm install husky --save-dev
复制代码

而且在 package.json 中的 scripts 字段中加入

"commitmsg": "validate-commit-msg"
复制代码

而后每次 git commit 以后，就会自动检查 commit message 是否合格。若是不合格，就会报错

husky > commit-msg (node v9.2.1)
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" !
change
husky > commit-msg hook failed (add --no-verify to bypass)
复制代码

生成 Change log

若是你的全部 commit 都符合 Angular 格式，那么发布新版本时， Change log 就能够用脚本自动生成。

生成的文档包括如下三个部分。

New features
Bug fixes
Breaking changes.

每一个部分都会罗列相关的 commit ，而且有指向这些 commit 的连接。固然，生成的文档容许手动修改，因此发布前，你还能够添加其余内容。

`conventional-changelog` 自动根据 `commit` 生成 `change log`

`conventional-changelog` 安装

npm install -g conventional-changelog-cli
复制代码

`conventional-changelog` 工做流

Make changes
Commit those changes
Make sure Travis turns green
Bump version in package.json
conventionalChangelog
Commit package.json and CHANGELOG.md files
Tag
Push

conventionalChangelog 这一步有两种选择

# 不会覆盖之前的 Change log，只会在 CHANGELOG.md 的头部加上自从上次发布以来的变更
$ conventional-changelog -p angular -i CHANGELOG.md -s -p 

# 生成全部发布的 Change log
$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0
复制代码

注意：

这里安装的是 conventional-changelog-cli，安装 conventional-changelog 会报 conventional-changelog: command not found 的错误
查阅了不少文章使用的是 conventional-changelog -p angular -i CHANGELOG.md -w，这样只能在命令行中 log 出 CHANGELOG 的内容，不会生成文件，若是要生成文件须要使用 conventional-changelog -p angular -i CHANGELOG.md -s。更多的 config 可使用 conventional-changelog --help 查看
还须要注意的是，在生成 changlog 以前，须要先使用 $ npm version [version] 更改版本号，而后再生成 changelog，这一步不少的博文都没有写，就会致使增量生成的 CHANGELOG 一直都有以前的 commit 记录。

自动判断版本号

上面步骤有两个须要优化的地方

须要在 conventionalChangelog 以前先要更改版本号
生成 CHANGELOG.md 以后又形成了新的改动，因此还须要再执行一遍提交

因此咱们须要自动化的执行这些，commitizen 还依据 conventional message，建立起一个生态

conventional-changelog-cl：经过提交记录生成 CHANGELOG.md
conventional-github-releaser：经过提交记录生成 github release 中的变动描述
conventional-recommended-bump：根据提交记录判断须要升级 Semantic Versioning 哪一位版本号

使用这些工具能够简化发布流程。

cp package.json _package.json &&
preset=`conventional-commits-detector` && 
echo $preset &&
bump=`conventional-recommended-bump -p angular` &&
echo ${1:-$bump} &&
npm --no-git-tag-version version ${1:-$bump} &>/dev/null &&
conventional-changelog -i CHANGELOG.md -s -p ${2:-$preset} &&
git add CHANGELOG.md package.json package-lock.json &&
version=`cat package.json` &&
git commit -m'docs(CHANGELOG): $version' &&
mv -f _package.json package.json &&
npm version ${1:-$bump} -m 'chore(release): %s' &&
git push --follow-tags 
复制代码

在你的项目中规范 `commit message` 而且根据 `commit` 自动生成 `CHANGELOG.md`

安装依赖

npm install -g commitizen conventional-changelog conventional-changelog-cli conventional-commits-detector conventional-recommended-bump husky validate-commit-msg

复制代码

安装完成以后版本以下（我遇到过 conventional-recommended-bump 是 4.x 的版本会报错Error: Unable to load the "angular" preset package. Please make sure it's installed.。下降下版本就好。

/usr/local/lib
├── commitizen@3.0.4
├── conventional-changelog@2.0.3
├── conventional-changelog-cli@2.0.5
├── conventional-commits-detector@0.1.1
├── conventional-recommended-bump@0.3.0
└── npm@6.1.0
复制代码

在 package.json 中增长 script 字段

"changelog": "cp package.json _package.json &&preset=`conventional-commits-detector` && echo $preset && bump=`conventional-recommended-bump -p angular` && echo ${1:-$bump} && npm --no-git-tag-version version ${1:-$bump} &>/dev/null && conventional-changelog -i CHANGELOG.md -s -p ${2:-$preset} && git add CHANGELOG.md package.json package-lock.json && version=`cat package.json` && git commit -m'docs(CHANGELOG): $version' && mv -f _package.json package.json && npm version ${1:-$bump} -m 'chore(release): %s' && git push --follow-tags "
复制代码

使用使用 git cz 就能够根据提示，生成自动化的 commit message 使用 npm run changelog 生成 changelog, tag, 升级 version, 并自动执行 git push

问题

改方案还有一个问题还没有解决，就是使用 conventional-recommended-bump 更换推荐版本，我实验的项目都是只改动了中间的版本号，若是你的项目对版本号要去比较严格，建议使用手动更换版本号的方式。

规范你的 commit message 而且根据 commit 自动生成 CHANGELOG.md

commit message 的做用

commit message 的格式

Header

type

scope

subject

body

Footer

Commitizen -- 自动生成合格的 commit message

安装