使用 conventional-changelog-cli 生成 changelog

Git commit 格式

AngularJS commit 规范

首先,为了能够自动生成 Changelog,需要规范Git commit 的格式,这里采用 the AngularJS commit conventions 的写法。

每次 commit 由 header,body,footer 三部分组成:

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

其中只有 header 是必须要有的,body 和 footer 可以省略。

Revert

如果要 revert 之前的一次 commit, 需要在开头加上 revert:, 然后是要 revert 的 commit 的 header 部分。 body 部分应该是: This reverts commit <hash>.,hash 是要被 revert 的 commit 的 SHA 值。示例见 Body 部分

Type

必须是以下几种:

  • feat: 新 feature
  • fix: 修复 bug
  • docs: 修改 Documentation
  • style: 格式,无关代码含义
  • refactor: 重构,即非修复 bug,也非增加 feature
  • perf: 性能改进
  • test: 增加或修改测试用例
  • chore: 修改 build 过程或辅助脚本

通常 type 是 feat,fix,或 perf的话,commit 信息会出现在 changelog 中。但是无论 type 为什么,如果 footer中有任何重大修改 (Breaking Changes),commit 信息永远会出现在 changelog 中。关于 footer 和 Breaking Changes, 见 Footer 部分

Scope

可以以任意名词指明 commit 修改的范围。Scope 可以省略。

如果超过一种,可以用 * 表示。

Subject

是对修改作出的简洁描述,不超过70字,全部小写且结尾无(.)

示例:

1
feat(pencil): add 'graphiteWidth' option

Body

是对修改作出的详细描述。

revert 某个 commit,并在 body 中注明,见示例:

1
2
3
revert: feat(pencil): add 'graphiteWidth' option
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Footer 应该包含两种信息,或者是描述重大修改 (Breaking Changes), 或者是指明关闭某个 issue (Referencing issues)。在 commit 中关闭 GitHub issue 见 reference GitHub issues that this commit closes

Breaking Changes 需要以 BREAKING CHANGE: 开头,紧随其后是一个空格或空两行,然后是相关描述。示例:

1
2
3
perf(pencil): remove graphiteWidth option
BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reason.

Referencing issues 关闭多个 issue 示例:

1
2
3
fix(graphite): stop graphite breaking when width < 0.1
Closes #28, #29, #30

Git commit message 模版

为了方便 Git commit message 规范化,采用以下模版:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# <type>(<scope>): <subject>
# <body>
# <footer>
# -- Type --
# Should be one of the following:
# * feat: New feature
# * fix: Bug fix
# * docs: Changes to documentation
# * style: Formatting, missing semi colons, etc; no code change
# * refactor: Refactoring production code
# * test: Adding missing tests, refactoring tests; no production code change
# * chore: Updating grunt tasks etc; no production code change
# -- Scope --
# Scope is just the scope of the change.
#
# -- Subject --
# Subject should use impertivite tone and say what you did.
#
# -- Body --
# The body should go into detail about changes made.
#
# -- Footer --
# The footer should contain any JIRA (or other tool) issue references or actions.
#

另存到 ~/.git_commit_msg.txt ,并添加到全局配置中:

1
$ git config --global commit.template ~/.git_commit_msg.txt

也可以采用 Commitizen 向导工具,这里不展开介绍了。

生成 Changelog

安装 conventional-changelog-cli, 并执行:

1
2
3
$ npm install -g conventional-changelog-cli
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -s

此命令采用增量的方式添加新的 commit 信息, -i表示输入文件 ,-s表示输出到相同文件。如果是首次使用这个工具,并想生成所有的 changelog,可以执行:

1
$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0

该命令会覆盖以前的 changelog, -r表示从最新的 release 向前追溯有多少个 release 被生成,0表示重新生成所有 changelog。

更多参数,参考conventional-changelog --help

这是一个生成的示例:

1
2
3
4
5
6
7
8
9
10
11
12
<a name=""></a>
# (2016-12-07)
### Bug Fixes
* **firebase:** using single instance to get firebasedatabase ([647f483](https://xxx/commits/647f483))
### Features
* **firebase:** add firebase library ([585c89c](https://xxx/commits/585c89c))

Reference

Git Commit Guidelines

GitHub commit message conventions

Convention examples

The Art of the Commit Message

conventional-changelog-cli

Commit message 和 Change log 编写指南