自动产出changelog-第二节：自动产出

Posted 2021-09-14 帕奇式

背景

接上一篇《自动产出changelog-第一节：规范提交代码》调研的后续，本文将基于 angular.js格式 的提交内容围绕自动化产出进行后续调研。研究的方向为产出内容的工具是否支持各种自定义特性，能否帮助我们实现团队的风格及自动化过程中的一些问题。

简述

在调研的过程中大量的文章都会推荐使用 conventional-changelog/conventional-changelog 进行changelog的产出，而其他包含更丰富功能的库背后使用的依旧是这个工具进行内容的产出。其作者还制作了 conventional-changelog/standard-version 和 conventional-changelog/standard-release 两套功能更为丰富的工具供我们使用，standard-release具有一个规范的使用前提，所以这个规范并不符合我们团队的情况，下文讨论将围绕standard-version进行。而另一个工具叫 release-it/release-it 的近三年比 conventional-changelog更活跃，具体选择哪个工具好？下面将给出参考。

standard-version

项目安装

$ npm i --save-dev standard-version

在package.json加上下面这段内容后，调用 npm run release 使用

{
  "scripts": {
    "release": "standard-version"
  }
}

全局安装

$ npm i -g standard-version # 使用 standard-version

直接使用

$ npx standard-version

调用standard-version后会输出以下内容：

$ npx standard-version
√ bumping version in package.json from 0.2.0 to 0.2.1
√ bumping version in package-lock.json from 0.2.1 to 0.2.1
√ outputting changes to CHANGELOG.md
√ committing package-lock.json and package.json and CHANGELOG.md
√ tagging release v0.2.1
i Run `git push --follow-tags origin master && npm publish` to publish

standard-version会为我们做以下行为：

1. 缓存当前文件变化
2. 将历史回退至最后一个git标签的位置（查看package.json中提供的信息来定位git标签）
3. 更新版本号
4. 产出changelog文件
5. 提交变动
6. 打上新版本的git-tag

产出的changlog长这个样子：

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### 0.2.1 (2021-04-09)


### Features

* 初次化 ([9d06990](http://gogs.infzm.com:22403///commit/9d06990aa9d4c82acfe4b0fd9c28c65dbdd89715))
* 增加逻辑 ([e8667aa](http://gogs.infzm.com:22403///commit/e8667aa136bec4836765deb31b60a76c48cad017))
* 新增一行输出 ([c747a34](http://gogs.infzm.com:22403///commit/c747a347d2d53430c676b296bb2c06aacc4de937))

预览操作行为（不会实际执行），可使用 --dry-run 尝试操作：

$ npx standard-version --dry-run

到这步都是使用默认的方式进行，后面开始探讨自定义内容。

自定义

上面产出的changelog内容并不是每个团队都认可的，必定存在需要改动的期望；其次还有在CI/CD工具中需要配合其他工具一并使用，对于standard-version丰富的功能能否跳过也是一个重要的考量；最后一个是起自动更新版本号，版本号具有一定的语意（具体参考这篇文章《使用npm命令行更新版本号》），能否支持更细化的控制，就是另一个重要的考量了。

所以最后需要弄清楚：

• 能否自定义产出的changelog内容？能做何种程度的自定义呢？
• 能否跳过一些standard-version提供的行为呢？
• 能否自定义更新版本号呢？

自定义产出Changelog内容

官方文档中提到，要自定义配置可以选择两种方式，写在package.json里面，或是令建一个.versionrc文件。standard-version将会在这两处获得配置内容。下面选用独立文件的配置方式进行说明。

创建.versionrc文件

$ touch .versionrc

.versionrc内容为JSON格式，影响changelog产出设置的配置内容包含以下这些：

配置项	类型	描述
header	String，字符串，支持\'\\n\'	文档的头部内容，默认值为：\'# Changelog\\n\\nAll notable changes to this project will be documented in this file. See standard-version for commit guidelines.\\n\'
types	Array, type对象数组	用于配置输出的内容。type对象包含：type 对应commit录入中的type；section 展示的文字内容;hidden 是否隐藏；例子：{"type": "feat", "section": "Features", "hidden": false}
preMajor	Boolean，布尔值	用于控制是否显示1.0.0版本之前的changelog。
commitUrlFormat	String，字符串	提交内容可访问地址，默认：{{host}}/{{owner}}/{{repository}}/commit/{{hash}}
compareUrlFormat	String，字符串	两个提交对比的可访问地址，默认：{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}
issueUrlFormat	String，字符串	提问内容地址，默认：{{host}}/{{owner}}/{{repository}}/issues/{{id}}
userUrlFormat	String，字符串	提交人可访问的地址，默认：{{host}}/{{user}}
releaseCommitMessageFormat	String，字符串	用于格式化自动生成的发布落实消息的字符串。
issuePrefixes	Array<String> or String，字符串或者字符串数组	用于检索提问内容的标识，如：#39；默认是：[\'#\']

格式文档来自这里：《Conventional Changelog Configuration Spec (v2.1.0)》，上面用到的模板变量（如：{{host}}）在前面格式文档最后有提交。

整合到文件内容如下面例子：

{
    "header":"# 更新历史 \\n\\n",
    "types": [
        {"type": "feat", "section": "✨ Features | 新功能"},
        {"type": "fix", "section": "
以上是关于自动产出changelog-第二节：自动产出的主要内容，如果未能解决你的问题，请参考以下文章
 
 测试投入与产出
 测试投入与产出
 管理课
 贴吧玩法--学习总结
 软件智能在敏捷开发中的应用
 数学建模之数据包络分析（评价投入产出比的模型）