使用 commitizen 和 standard-version

本文为译文，原为为：Christian Ing Sunardi: Automate JavaScript project versioning with commitizen and standard-version

其实手动更新版本号，changelog, 创建 git tags 还是比较麻烦的。有没有更好的方法？别怕，使用 standard-version ，只需要一行命令，就会帮你搞定一切！为实现自动化版本控制，有一些基础配置需要做。

安装 commitizen

在使用 standard-version 之前，需要遵循 Conventional Commit Specifications 来进行标准化的 commit message 编写。这是因为 standard-version 是基于 commit 类型来更新版本号的（feature 会更新 minor, bug fix 会更新 patch, BREAKING CHANGES 会更新 major）。commitizen 可以帮助我们提交符合 Conventional Commit Specifications 的 commit message。

1. 在你的 JavaScript 项目中安装 commitizen：

npm install -D commitizen

2. 设置 changelog adapter：

commitizen init cz-conventional-changelog --save-dev --save-exact

3. 在 package.json，中增加如下脚本：

"scripts": {
  "commit" : "git-cz"
}

首先我们 git add . 文件，然后 npm run commit，此时 commitizen 会通过 CLI 对我们进行询问：

选择提交类型后，会需要我们填写详细信息：

detail.png

至此，我们的修改已经被成功提交，可以开始配置 standard-version 了。

安装 standard-version

当我们使用 commitizen 进行标准化提交之后，我们就可以使用 standard-version 进行版本管理自动化了，包括更新 CHANGELOG.md，以及使用 git tag。

1. 安装 standard-version：

npm install -D standard-version

2. 在 package.json 中编写响应的脚本：

"scripts": {
  "commit" : "git-cz",
  "release": "standard-version"
}

为了合理的使用 standard-version，我们首先需要 git add . 文件，然后执行 npm run commit，最后执行 npm run release。

CHANGELOG.md 配置

默认情况下，standard-version 只会在 CHANGELOG.md 中记录 feat 和 fix 类型的提交。如果想记录其他类型的提交，需要如下步骤：

• 在项目的根目录下创建一个名为 .versionrc 的文件，并粘贴复制一下内容：

// .versionrc
{
  "types": [
    {"type": "chore", "section":"Others", "hidden": false},
    {"type": "revert", "section":"Reverts", "hidden": false},
    {"type": "feat", "section": "Features", "hidden": false},
    {"type": "fix", "section": "Bug Fixes", "hidden": false},
    {"type": "improvement", "section": "Feature Improvements", "hidden": false},
    {"type": "docs", "section":"Docs", "hidden": false},
    {"type": "style", "section":"Styling", "hidden": false},
    {"type": "refactor", "section":"Code Refactoring", "hidden": false},
    {"type": "perf", "section":"Performance Improvements", "hidden": false},
    {"type": "test", "section":"Tests", "hidden": false},
    {"type": "build", "section":"Build System", "hidden": false},
    {"type": "ci", "section":"CI", "hidden":false}
  ]
}

• "type" commit 类型
• "section" 不同的 commit 类型所在 CHANGELOG.md 中的区域
• "hidden" 是否在 CHANGELOG.md 中显示

开发工作流

截至目前，所有的配置已经设置完毕。让我们用一个真实的开发工作流来梳理一下 *commitizen * 与 standard-version 的使用。

workflow.png

1. [feature-branch] stage 更改的文件：

git add .

2. [feature-branch] 用 git-cz 来提交文件：

npm run commit

• 选择提交类型（feat, refactor, fix, 等等）
• 提供简短描述
• （可选）提供长描述
• 确定本次提交是否为 BREAKING CHANGES
• （可选）提供 JIRA issue

3. [feature-branch] 推送远端

git push origin <feature-branch>

4. [Bitbucket] 向 master 分支提交 Pull Request
5. [master] 成功合并后：
   • 执行命令 npm run release (自动更新版本号，自动更新 CHANGELOG.md, 自动创建 git tag)
   • 将更改和 git tags 推送至远端:

   git push --follow-tags origin master
   

6. Relax and enjoy 🍕

总结

使用以上流程进行版本发布是一种非常好的最佳实践。因为我们可以非常轻松的追溯虽有的更新。并且一切都是自动化的。

常见坑🤔

• 如果当前版本没有主版本号，则BREAKING CHANGES commit 不会更新主版本号！！！比如当前版本号为 0.1.2，我们运行 npm run release 则只会更新 minor 和 patch 版本号（参考：https://github.com/conventional-changelog/standard-version/issues/429
  ）。
• 为了正确的更新主版本号，我们需要显式的进行：

  standard-version -- --release-as major
  

注意： standard-version 后的 双横线 -- 是必须的。在 --release-as 和 major 之间是有空格的。

• 此后，我们再次发布包含 BREAKING CHANGES 类型的提交，则能够自动更新主版本号👍🎉。
• 如果有多次提交，则版本号更新是有优先级的：
  • major 或者 BREAKING CHANGES 高于 minor 和 patch
  • minor 高于 patch