约定式提交规范三部曲（三）之 conventional-changelogConventional Changelog

什么是 conventional-changelog

conventional-changelog 是一个广泛使用的工具和约定，它旨在帮助开发人员自动生成符合约定式提交规范（Conventional Commits）的变更日志 CHANGELOG.md。

而 conventional-changelog-cli 是一个用于生成遵循约定式提交规范（Conventional Commits）的变更日志的命令行工具。它可以根据代码仓库的提交历史自动生成详细的变更日志，帮助项目团队更好地跟踪和记录版本发布的变动。

安装

npm install -g conventional-changelog-cli

# 生成 CHANGELOG.md
cd my-project
conventional-changelog -p angular -i CHANGELOG.md -s

上面的命令不会覆盖任何之前的变更日志，因为 -r 选项默认为 1。上面命令会从 git 的提交历史中基于最后一次的语义化版本（semver）标签进行生成变更日志。

如果希望重新生成所有变更日志，覆盖当前 CHANGELOG.md 文件，使用如下命令：

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

使用 angular 预置，默认情况下 conventional-changelog 只会匹配以下四种提交类型的内容：

feat: 新增功能；
fix: 修复 bug；
perf: 改进性能的代码更改；
revert: 代码回滚；

📌 conventional-changelog 是根据 package.json 文件中的 version 与 git 中的版本标签进行对比的，二者缺一不可。

常用选项

conventional-changelog 常用选项：

-i：读取 CHANGELOG.md 的输入文件。
-o：输出文件。
-p：预置名称，基本都会使用 angular 规范标准。
-u：代表未归入版本（unrelease）的日志。
-r：代表输出几个版本，0 则代表输出所有并覆盖输出文件。
-s：代表输出与输入为相同文件。

推荐工作流

Make changes：做出变更；
Commit those changes：提交变更；
Bump version in package.json：修改 package.json 中的版本号；
conventionalChangelog：运行命令生成 CHANGELOG.md；
Commit package.json and CHANGELOG.md files：提交版本号与变更日志的变更；
Tag：提交打版本标签；
Push：推送提交；

# 完整流程演示

# 1. 创建项目
mkdir example && cd example

# 2. 初始化 git
git init

# 3. 初始化 node 与安装 conventional-changelog
npm init
npm install --save-dev conventional-changelog-cli

# 4. git 忽略
echo "node_modules" > .gitignore

# 5. 提交变更
git add . && git commit -m "build(env): init"

# 6. 模拟新增特性与修复 bug
touch {a,b}

# 7. 提交变更
git add a && git commit -m "feat(a): new a"
git add b && git commit -m "fix(b): fix b"

# 你的提交日志看起来应该是这个样子
git log --one-line
19316df (HEAD -> master) fix(b): fix b
adc82e3 feat(a): new a
c73e259 build(env): init

# 8. 修改 package.json 版本号
sed -i 's/"version": "1.0.0"/"version": "1.0.1"/' package.json

# 9. 生成 CHANGELOG.md
npx conventional-changelog -p angular -i CHANGELOG.md -s

# 10. 提交版本号与变更日志
git add . && git commit -m "build: v1.0.1 版本并更新 CHANGELOG.md"

# 11. 提交打版本标签
git tag v1.0.1 HEAD

# 至此流程结束，接下来就是循环上述 6 ～ 10 步骤

使用 `npm version` 方式

npm pkg set scripts.version="conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md"

执行上面的命令或者将下面的内容加入 package.json，添加 npm version 钩子，在执行 npm version 时，将自动运行该脚本。

{
  "scripts": {
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md"
  }
}

正常工作流

Make changes：做出变更；
Commit those changes：提交变更；
Pull all the tags：拉取所有标签；
Run the npm version [patch|minor|major] command：运行 npm version 进行版本升级；
Push：推送提交；

同时也可挂载 preversion 与 postversion 进行前置与后置处理。

注意：与推荐工作流相比，npm version 运行后会同时升级 package.json 中的版本，并且提交一个版本标签的 git 提交，之后才会变更 CHANGELOG.md 的内容，这就导致了升级的版本 git 提交中并未包含更新后的 CHANGELOG.md 文件。

约定式提交规范三部曲（三）之 conventional-changelog

什么是 conventional-changelog

安装

常用选项

推荐工作流

使用 npm version 方式

正常工作流

下一步

使用 `npm version` 方式