使用 semantic-release 自动发版

2022-03-24  本文已影响0人  anyesu

前言

最近新项目准备做自动发版，就去研究了一下 semantic-release 。

什么是 semantic-release

Fully automated version management and package publishing

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.

This removes the immediate connection between human emotions and version numbers, strictly following the Semantic Versioning specification.

用人话说就是一个完全自动化的工具，可以帮助你做版本号管理、生成 changelog ，并且发布到包管理器 ( 比如 npm ) 。

如何使用 ( 官方文档 )

  1. Install semantic-release in your project

  2. Configure your Continuous Integration service to run semantic-release

  3. Configure your Git repository and package manager repository authentication in your Continuous Integration service

  4. Configure semantic-release options and plugins

cd your-module
npx semantic-release-cli setup

# For Node modules projects
npm install --save-dev semantic-release

# Then in the CI environment
npx semantic-release

以上是官方文档的内容，操作真的是很简单，简单到不知道它是干嘛的，简单到后面步入一个个坑不知道怎么解决。我照着官方文档折腾了几个小时愣是没跑通，一直在 error 。要不是看在很多项目 ( 比如 octokit ) 都在用它，我都想直接放弃了。

官方文档只是告诉你需要安装这么一个包，有哪些参数，剩下的都没细说，就算有也是藏在某个角落里生怕别人找到：

  1. 是否需要新建 GitHub 仓库？

  2. 如何配置 GitHub 和 npm 的 token ?

  3. 何时触发 发布 操作的？手动执行命令？push ？

  4. 如何测试？一定要在 CI 环境中？

正确打开方式

我特地建了一个新仓库 semantic-release-test 来演示效果。感兴趣的朋友可以照着我的提交记录走一遍流程。

原理分析

首先，我们结合 semantic-release 和 semantic-release:local 两个命令的日志看下它究竟做了什么

  1. 加载插件。

  2. 判断是否在 CI 环境中，不是则跳过执行插件的一些生命周期。

  3. 检查远程仓库是否存在，以及合法的分支。

  4. 检查是否有仓库的写入权限。

    这一步比较坑爹，如果没有设置 GITHUB_TOKEN 报错竟然是版本落后？？？

    Run automated release from branch master on repository https://github.com/iewgggg/semantic-release-test.git in dry-run mode
The local branch master is behind the remote one, therefore a new version won't be published.

    设置 GITHUB_TOKEN 后再看日志感受下区别

    Run automated release from branch master on repository https://[secure]@github.com/iewgggg/semantic-release-test.git in dry-run mode
√  Allowed to push to the Git repository

    这个问题也是我 debug 源码后才发现的。

  5. 检查 NPM_TOKEN 是否存在，并写入到 temp 目录的 .npmrc 文件中。

  6. 检查当前分支是否存在符合 语义化版本 的 tag，存在则为当前版本号。

  7. 对比 远程仓库 是否有新的提交记录，无则终止。

  8. 插件 @semantic-release/commit-analyzer 开始对 新的提交记录 逐条分析，筛选符合 提交规范 的记录， 筛选结果 为空则终止。

  9. 如果存在 当前版本号 ，则根据 筛选结果 确定升级类型 ( MAJOR / MINOR / PATCH ) 计算 新的版本号 ，否则 新版本号 为 1.0.0 。

  10. 插件 @semantic-release/release-notes-generator 再对 新的提交记录 逐条分析生成 changelog 。

  11. 插件 @semantic-release/npm 将 新的版本号 重新写入到 package.json 文件中。

  12. 插件 @semantic-release/git 对修改后的 package.json 进行 提交 和 推送 。

    插件默认配置还会修改 CHANGELOG.md 文件，本文中配置为只修改 package.json

  13. 添加新版本号 tag 。

  14. npm 打包 并 发布 ，如果 package.json 设置了 "private": true 则跳过。

  15. 发布到 GitHub ，包括压缩包和 changelog 。

整个流程比较清晰了，主要操作也是通过几个插件来完成，所以通过对插件的组合、配置来实现一些个性化的需求。

缺点

  1. semantic-release 强依赖于远程仓库的分支状态，所以在正式使用前测试会非常麻烦，反复测试需要反复重置远程仓库的状态，而且网络不好就更恶心了。

  2. release 中的 changelog 是发布一个版本生成一次的，这就意味着仓库迁移的话，历史记录就没有了，只剩下 tag 。

    如果没有使用插件 @semantic-release/git 的话可以不断 reset HEAD 来恢复一个个版本，当然这也很麻烦。

FAQ

IDEA 插件推荐

  1. Git Commit Template

    通过表单的形式结构化输入 commit message 。

    符合 AngularJS 的 Git Commit Guidelines 规范。

  2. Gitmoji

    根据输入的内容来选择 emoji 表情 的表达式。

    Reference commit rules / 中文提交规则

  3. Gitmoji-Unicode

    Gitmoji 插件的 fork 版本，可以直接显示 emoji 表情 而非表达式。

两个插件都挺不错的，缺点就是写死了不可配置，再加上几年没维护了，用起来有点尴尬。

最后

按照文中的配置，基本上满足我的需求了：

  1. 自动化版本管理，推送代码或者合并 PR 即可发版。

  2. 自动生成 changelog ，不再需要单独去写。

  3. 自动发布到 npm ( 😅 直接省去了学习 npm 发包的步骤 ) 。

  4. 发布后对应的 PR 和 issue 下会添加 发布通知 的评论，就不需要自己再手动通知了。

转载请注明出处：https://github.com/anyesu/blog/issues/37

上一篇 下一篇

猜你喜欢

热点阅读