规范你的 commit message 并且根据 commit 自动生成 CHANGELOG

栏目: JavaScript · 发布时间: 6年前

内容简介：项目地址：一个好的项目通常都是多人合作的结果，然而每个人有每个人的开发习惯，并不统一。所以 commit message 就显得格外的重要。有些不规范的 commit 可能过个一个月之后你自己都不知道当时的提交目的了ﾍ(;´Д｀ﾍ)，

项目地址： github.com/sunshine940…

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

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

所以，为了能使得日后复（zhao）盘（guo）的时候更加的方便，团队之间遵守同一套 commit message 规范还是很有必要的。

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

commit message 的作用

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

commit message 的格式

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

使用 git commit 可以提交多行 commit message .

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

规范你的 commit message 并且根据 commit 自动生成 CHANGELOG

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 andCHANGELOG.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 ，创建起一个生态

使用这些工具可以简化发布流程。

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

  1. 安装依赖
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
复制代码
  1. 在 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 "
复制代码
  1. 使用 使用 git cz 就可以根据提示，生成自动化的 commit message 使用 npm run changelog 生成 changelog, tag, 升级 version, 并自动执行 git push

问题

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


以上所述就是小编给大家介绍的《规范你的 commit message 并且根据 commit 自动生成 CHANGELOG》，希望对大家有所帮助，如果大家有任何疑问请给我留言，小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持！

查看所有标签

猜你喜欢:

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。

码农书籍
沸腾十五年

沸腾十五年

林军 / 中信出版社 / 2009-7 / 59.00

覆雨翻云的中国网事； 荡气回肠的产业传奇；虚拟世界的真实讲述；万象网络的还原走笔。 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 本书记录了一群在中国创造属于自己历史的人和他们的故事，他们是中国互联网自1995年兴起的波澜壮阔中的弄潮儿和财富新贵的代表：马化腾、丁磊、张朝阳、马云、陈天桥、李彦宏、史玉柱、田溯宁、张树新、王志东、王峻涛、雷军、......一起来看看 《沸腾十五年》 这本书的介绍吧!

码农工具
HTML 压缩/解压工具
HTML 压缩/解压工具

在线压缩/解压 HTML 代码

RGB转16进制工具
RGB转16进制工具

RGB HEX 互转工具

HEX HSV 转换工具
HEX HSV 转换工具

HEX HSV 互换工具

  • New
  • 文章
  • 话题
  • 教程
    • 关注 码农网 公众号
    版权所有，保留一切权利！© 2018-2024 码农网 粤ICP备17054400号-3