概述
npm 包 changeset 是一个用于生成版本更新日志的工具,能够记录变动信息并生成易于阅读的模板。使用 changeset 有助于团队成员更加清晰地了解项目中的变动,并且更加便捷地查看历史变动记录。
本文将介绍如何使用 changeset 来记录版本更新日志,从安装开始,到配置和使用,再到最佳实践,详细地介绍每个步骤。
安装
运行以下命令来安装 changeset:
npm install --global changeset
配置
初始化
在项目根目录下运行以下命令,以初始化 changeset:
changeset init
这将创建一个 changeset.config.js
配置文件,存储 changeset 的一些选项。
配置选项
随后,我们需要配置一些选项。
packages
packages 表示需要被记录变动信息的包。
在 changeset.config.js
中添加以下代码:
module.exports = { // ...其他配置选项 packages: ['package-1', 'package-2'], };
这样,只有 package-1
和 package-2
的变动信息才会被记录。
release
release 表示当前的版本。初始版本 release 为 0.0.0
。
在 changeset.config.js
中添加以下代码:
module.exports = { // ...其他配置选项 release: { tag: 'latest', name: '0.0.0', }, };
这样,在记录日志时,会从 release 的版本开始。比如,如果 release 为 2.0.0
,则只会记录 2.0.0
之后的变动信息。
changelog
changelog 表示生成日志的格式。
在 changeset.config.js
中添加以下代码:
-- -------------------- ---- ------- -------------- - - -- --------- ---------- - ------------ -- ---------- --- ------ ----------- -------- --- ------ ----- -- ----- ---- -------- - - ----- -------- -------- ------- - -- -- --
这里使用了默认配置,生成的格式如下:
-- -------------------- ---- ------- -- -------- --- --------- ---- ----- - ------- --- ----------------------------------------------- - ------- --- ----------------------------------------------- --- --------- ---- ----- - ------- --- -----------------------------------------------
其中 commitLimit
表示每个包展示的提交数量,tagPrefix
表示标签的前缀,group
表示分组的名称,version
表示版本号的格式,date
表示日期的格式,changes
表示变动类型。我们也可以根据实际需求进行更改。具体的配置项和示例可以参考 changeset 官方文档。
常用命令
安装和配置完成后,我们可以运行以下命令来使用 changeset。
changeset status
执行 changeset status
可以查看未被记录的提交。
changeset add
执行 changeset add
可以将未被记录的提交添加到变动信息中。
changeset version
执行 changeset version
可以为 packages 设定新版本,生成更新日志。
changeset release
执行 changeset release
可以将更新日志发布为 stable 版本。
最佳实践
结合 CI/CD
为了保证每次部署时都能及时更新版本和更新日志,我们可以将 changeset 集成到 CI/CD 流程中。
以 Jenkins 为例,我们可以在 Jenkinsfile 中添加以下代码:
-- -------------------- ---- ------- -------- - -- --------- ------ - -- ------- ------------- --------- - ----- - -- ---------- -------- - - -------------- - ----- - -- ------- - ---- - ------ - -- ---------- -- ---------- -------- - - - - -
这样,每次构建时,changeset 就会自动更新版本和更新日志,并发布为 stable 版本。
基于模板生成更新日志
我们可以使用模板来生成更新日志,改为满足特定需求的格式。
请按照以下步骤操作。
创建模板文件
在项目根目录下,创建一个名为 template.ejs
的文件,内容可以是以下示例代码:
-- -------------------- ---- ------- ----- -- ------------------------------- --------- - -- ------- --------------- ------- -- -- ---------------- -- ----------------------- - -- -- -------------------------------- --------- ---- - -- ------- ------------ ------- ---- -- ------------------------------ ------ - -- ------- ---- ------- -- -- -- ----- -- -- -- -- - -- -- -- --
更改配置
在 changeset.config.js
中更改 changelog
配置:
module.exports = { // ...其他配置选项 changelog: { preset: 'angular', output: 'template.ejs', }, };
这里使用 preset: 'angular'
来告诉 changeset 使用 Angular 风格的配置生成更新日志,最后指定输出为 template.ejs
。
运行 changeset
运行 changeset release
来生成更新日志。
集成 GitHub Action
除了结合 CI/CD 使用 changeset,我们还可以将 changeset 集成到 GitHub Action 中,在每次 pull request 和 merge 后自动生成更新日志并发布为 release 版本。
请按照以下步骤操作。
创建 GitHub Action
在你的 GitHub 仓库中,转到 Actions 选项卡,点击 New workflow
按钮,选择 Set up a workflow yourself
选项,即可创建一个新的 GitHub Action。
在 .github/workflows/changeset.yml
文件中添加以下代码:
-- -------------------- ---- ------- ----- --------- --- ------------- ------ - ------ - ----------- ----- ---------------- - --- ----- ---------- -------- ------------- ------ - ----- -------- ---- ----- ------------------- - ----- ----- ------- ----- -------------------------- ----- ------------- ------ - ----- ------- ------------ ---- --- ------- - ----- ------ ----- ---- --------- ------ - ----- --- --------- ---- --------- --- - ----- ------- --------- ---- --------- ------- ---- ---------------- --- -------------------- -- - ----- ------ ------- ----- ------------------------------ --- -------- ----- ----- ------- --- --------------- -- --------- --- --------------- -- ----------- ----- ------ ----- ----- - --- ---------------- -- ---------- --- ---------- -- ---- ------------- --- -------------------- --
这里运行了一个名为 changeset
的任务,其中务必添加 NODE_AUTH_TOKEN
环境变量,否则发布 release 版本时将因为权限问题出现错误。
配置 Secrets
在 GitHub 仓库设置中,转到 Secrets
选项卡,添加一个名为 NODE_AUTH_TOKEN
的 key,将你的 npm token 存储在其中。
完成
完成上面的步骤后,你就可以愉快地使用 changeset 了。
结语
通过本文,我们可以学习使用 changeset 记录版本更新日志,从安装开始到使用,再到最佳实践,了解了如何使用 changeset 提高项目管理效率。希望本文对读者有所帮助。
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/changeset