组件库从开发到维护全链路讲解（六）自动且高效的生成changelog

HashTang
2,013 阅读4分钟

本篇文章为《前端组件库的开发与维护》系列的第六篇文章。本文案例在线文档：calendar.hxkj.vip。GitHub 仓库：github.com/TangSY/vue3…。

作为一个经常使用开源组件库/框架的你来说，一定会发现这样一个情况，不管它的用户量有多少，都会配有对应的 changelog，例如：Element-ui、Antd 等。

为什么需要 changelog

为什么他们都会提供 changelog 呢？我认为清晰的 changelog，至少包含以下几个好处：

  1. 方便查看每个版本新增了哪些功能；
  2. 方便查看每个版本修复了什么 bug；
  3. 确定哪个版本有 break change。这个很重要，可以帮助用户提前预防由于盲目升级带来的 bug；

好处是知道了，我也想写了，那真的是每次版本迭代都手动维护这个文档吗？

还记得 上一篇文章 中提到规范化的 commit 信息可以用于生成 changelog 吗？没错，接下来咱们就是需要配合它来实现自动生成 changelog。

生成 changelog

这里介绍两种方式，具体使用哪种凭个人喜好。

1、conventional-changelog-cli

conventional-changelog-cli 默认推荐的 commit 标准也是来自 AngularJS规范，所以咱们不用做任何配置，直接拿来就用即可。

首先全局安装：

npm install -g conventional-changelog-cli

然后使用如下命令进行 changelog 的生成：

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

以上命令中：参数 -p 用来指定 angular 规范作为 commit 信息的标准；-i 表示从 CHANGELOG.md 文件中读取 changelog；-s 表示读写 changelog 为同一个文件。

执行完成之后，会在项目根目录中新建一个 CHANGELOG.md 文件，文件内容如下：

image.png

这里需要注意两点：

  • 第一点：上面那条命令产生的 changelog 是基于上次 tag 版本之后的变更所产生的，所以如果想生成之前所有版本 commit 信息产生的 changelog 则需要使用这条命令：
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

其中 -r 表示生成 changelog 所需要使用的 tag 版本数量，默认为1，全部则是0。

  • 第二点：由上面第一点可知，每次生成 changelog 都是基于 tag 版本的，所以每次版本迭代都必须打上 tag。否则的话，生成 changelog 永远只有一个版本。

那怎么样才能更方便的打 tag 和维护版本呢？其实 npm 自带的 version 命令就可以很轻松的同时搞定 tag 和版本管理了。

我们都知道每个 npm 包中都有一个 package.json 文件，如果要发包的话，package.json 中的 version 就是版本号了。

version 字段结构为：'0.0.0-0'。

分别代表：大号.中号.小号-预发布号，对应 major.minor.patch-prerelease。

咱们执行 npm version 加上对应的版本标签 可以自动更改 package.json 中对应的版本号。

例如：package.json 包中的 version 是1.0.0，然后执行如下命令：

npm version prerelease

执行完之后，package.json 的版本号则会变成 1.0.1-0。同时，会自动打上一个名为 v1.0.1-0 的 tag。

咱们执行 git tag -l 就可以看到这个 tag。

image.png

如果此时执行生成 changelog 的命令，就可以看到后续的提交信息都被生成出来了。

image.png

同样的，如果执行 npm version patch，意味着把 prerelease 版本标签去除，变为正式版。版本号就会变成 1.0.1。

2、Vant-cli

如果你是从第一篇一直看到这篇，就会知道咱们的组件库是基于 Vant-cli 搭建的，而 Vant-cli 刚好又提供了生成 changelog 的命令，那咱们就来试试看效果如何吧。

首先，在 package.json 文中添加如下 scripts：

 "changelog": "vant-cli changelog",

接着咱们执行一下 yarn changelog，可以看到控制台的提示，在根目录中生成了一个changelog.generated.md 文件，并且该文件没有加入 git 版本控制中。咱们打开看看，里面包含了最近一个版本的 changelog。

image.png

咱们要做的就是把这个 changelog 内容复制到真正的 CHANGELOG.md 文件中即可。

总结

今天这篇文章主要讲解了如何通过 commit 信息自动生成 changelog，分别有以下两种方法：

  1. conventional-changelog-cli 结合 npm version：这种方法适合任何项目，只是配置步骤较多而已。
  2. Vant-cli 提供的 changelog 命令：这种方法适合基于 Vant-cli 搭建的项目。

下一篇咱们来看看如何快速搭建一个高逼格且细致的文档网站。

对此系列感兴趣的，不妨一键三连（点赞 + 关注 + 收藏），方便跟进后续文章。

欢迎大家在评论区留下宝贵的建议！

本系列往期文章

开启掘金成长之旅！这是我参与「掘金日新计划 · 2 月更文挑战」的第 2 天，点击查看活动详情”

avatar
文章
阅读
粉丝