WTF-Solidity 仓库中的 OpenZeppelin Contracts 自动化发布流程:从 Changesets 到 npm 发布全解析

原创2026-09-15 22:26:491,753 阅读
文章标签:区块链Web3教育示例工程应用安全

WTF-Solidity 仓库中的 OpenZeppelin Contracts 自动化发布流程:从 Changesets 到 npm 发布全解析

OpenZeppelin Contracts 是一套广为使用的 Solidity 安全智能合约库,也是本仓库 lib/openzeppelin-contracts 目录所引入的依赖源码。其官方发布过程完全自动化:编译、打包、发布全部在 GitHub Actions 干净环境中完成,核心实现位于 release-cycle.yml 工作流。本文基于仓库内 RELEASING.md 文档,结合发布工作流、发布脚本与 Changesets 配置源码,完整还原其从合并新特性到发布新版 npm 包的端到端流程,读者读完后可掌握 release 分支模型、RC 预发布机制、CHANGELOG 管理方式以及自动化发布各阶段的触发条件与底层脚本实现。

发布流程总览:全自动化流水线

OpenZeppelin Contracts 的发布流程目标是最大限度降低人为失误和不确定因素。文档明确指出,编译、打包、发布这一整套动作均在一个干净的 CI 环境(GitHub Actions)中完成,由 release-cycle 工作流实现,从而保证发布过程的一致性与可靠性。

这套流水线在源码层面被拆解为五个彼此依赖的 Job,每个 Job 由状态机判定是否执行:

  • state:入口 Job,调用 state.js 计算当前仓库状态,并输出 start、changesets、promote、publish、merge 五个布尔标志,以及 is_prerelease 全局变量,后续 Job 均以这些标志作为执行开关;
  • start:当 start == 'true' 时执行,调用 start.sh 创建 release 候选分支并进入 prerelease 状态;
  • changesets:当 changesets == 'true' 时执行,通过 changesets/action@v1 生成版本更新 PR(对应文档中的 "Update PR to release");
  • publish:当 publish == 'true' 时执行,调用 pack.sh 与 publish.sh 完成打包与 npm 发布,随后创建 GitHub Release;
  • integrity_check:在 publish 成功后执行,调用 integrity-check.sh 校验发布产物与仓库源码的一致性;
  • merge:当 merge == 'true' 时执行,创建回灌 master 的 PR。

工作流顶部以 ASCII 图形式标注了五个 Job 的迁移路径:Development(开发)经手动触发(D)进入 RC-Unreleased,合并 release PR(M)或提交(C)推动状态在 RC-Released、Final-Unreleased、Final-Released 之间流转。其中:

  • 手动触发(D)用于开始新 RC 或提升到最终版;
  • 合并 release PR(M)触发 changesets 更新与发布;
  • 提交(C)触发重新评估,推动状态机前进。

Changesets:CHANGELOG 的自动化管理机制

文档强调,每次对代码库有影响的变更都必须附带一个 changeset,Changesets 工具负责 CHANGELOG.md 的自动化维护。

仓库中的配置文件 .changeset/config.json 给出了完整配置:

{
  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "OpenZeppelin/openzeppelin-contracts"
    }
  ],
  "commit": false,
  "access": "public",
  "baseBranch": "master"
}

参数说明:

  • changelog:指定由 @changesets/changelog-github 生成 CHANGELOG 条目,并关联到 OpenZeppelin 官方仓库,从而让每个变更条目自动链接到对应的 GitHub PR;
  • commit:false 表示 changesets 不会在版本命令执行时自动提交变更;
  • access:public 表示包以公共权限发布到 npm;
  • baseBranch:master,指明变更集合基于的主分支。

从 version.sh 可以看到版本更新的实际执行链路:

changeset version
scripts/release/format-changelog.js
scripts/release/synchronize-versions.js
scripts/release/update-comment.js
oz-docs update-version

即先由 changeset version 依据 changeset 文件统一提升各包版本号并生成 CHANGELOG,再由 format-changelog.js 格式化、synchronize-versions.js 同步各包版本、update-comment.js 更新文档注释中的版本引用,最后由 oz-docs update-version 同步文档版本。该脚本被 package.json 中的 "version": "scripts/release/version.sh" 命令关联,并由 release-cycle 工作流中 changesets/action 的 version: npm run version 调用。

分支模型:release-vX.Y 的 RC 演进与正式发布

分支命名与职责

发布周期围绕名为 release-vX.Y 的发布分支展开,每个分支从发布候选(release candidate,rc)开始,最终提升为正式版本。发布分支可以被从 master cherry-pick 过来的补丁更新,在旧版本维护场景下也可以直接向该分支提交。这些提交根据分支当前状态,决定产生一个新的 RC 还是补丁版本增量。

生命周期示意图

RELEASING.md 给出了完整的 git 图示意,其关键序列为:

  1. master 上合并新特性(Feature A、Feature B)后,从 master 拉出 release-vX.Y 分支;
  2. 分支上创建首个 RC 版本 Release vX.Y.0-rc.0;
  3. 回到 master 继续开发(Feature C),修复了 Bug(Fix A);
  4. 回到 release-vX.Y,将 Fix A cherry-pick 到发布分支,产出 Release vX.Y.0-rc.1,随后发布正式版 Release vX.Y.0;
  5. 将 release-vX.Y 合并回 master,继续开发(Feature D);
  6. 发现旧版本需要补丁(Patch B),同样从 master cherry-pick 到 release-vX.Y,产出补丁版本 Release vX.Y.1,再次合并回 master。

从源码确认的启动逻辑

state.js 中的判定函数证实了文档描述的触发规则:

  • shouldRunStart:isMaster && isWorkflowDispatch && !botRun,即只有在 master 分支上手动触发工作流且不是机器人运行时,才创建新 RC 分支;
  • shouldRunPromote:isReleaseBranch && isWorkflowDispatch && !botRun,即发布分支上的手动触发用于将 RC 提升为正式版;
  • shouldRunChangesets:发布分支上的 push 或机器人触发的手动运行,用于更新版本 PR;
  • shouldRunPublish:isReleaseBranch && isPush && !hasPendingChangesets && !isPublishedOnNpm,即发布分支上的 push、无待处理 changeset 且该版本尚未发布到 npm 时执行发布;
  • shouldRunMerge:发布分支 push、非 prerelease、当前为最终版本、无待处理 changesets 且不存在回灌 PR 时,创建回灌 master 的 PR。

启动脚本 start.sh 的流程为:先用 npx changeset status --output 将变更状态写入临时文件并防御性校验只有一个 release 目标,再解析 newVersion 中的 X.Y 部分生成 release-vX.Y 分支名,随后通过 npx changeset pre enter rc 进入 rc 预发布模式并提交 "Start release candidate",最后推送分支。推送失败时报错提示用户须从正确分支运行工作流。

预发布状态与 npm 已发布检查

state.js 通过 @changesets/pre 的 readPreState 判断是否处于 prerelease 模式,并通过 readChangesets 过滤掉已被预发布模式消费的 changeset;同时通过 isPublishedOnNpm 请求 https://registry.npmjs.com/${packageName}/${version} 检查当前版本是否已在 npm 上发布,以决定是否跳过 publish 阶段。

打包、发布与 npm dist-tag 策略

发布阶段的打包逻辑在 pack.sh 中实现。其 dist_tag 函数给出了一套完整的 npm 标签分配规则:

  1. 若处于预发布状态(PRERELEASE == 'true'),使用 next 标签;
  2. 若当前版本高于 npm 上的最新版(通过 npx semver -r ">$LATEST_NPM_VERSION" 判断),使用 dev 标签;
  3. 其余情况视为旧版本补丁(npm 发布必须有 tag),使用 tmp 标签。

随后在 contracts 目录执行 npm pack 生成 tarball,并输出 tarball_name、tarball、tag 三个供下游使用的变量。

发布脚本 publish.sh 的核心动作为:

  • 从 tarball 中提取包名与版本号(tar xfO "$TARBALL" package/package.json | jq -r .name);
  • 将 _authToken 写入 .npmrc(刻意转义 $ 以避免 token 落盘);
  • 执行 npm publish "$TARBALL" --tag "$TAG" 完成发布;
  • 根据 tag 进行清理:tmp 标签发布后立即删除;latest 标签发布时若存在指向同一版本的 next 标签则一并删除,避免旧版预发布标签残留。

在 release-cycle.yml 中,publish Job 还通过 actions/upload-artifact 上传 tarball 产物,供后续 integrity_check 下载校验。

发布产物完整性校验

publish 完成后,integrity_check Job 会重新下载 tarball 产物并执行 integrity-check.sh:

  1. 将 tarball 解压到临时目录;
  2. 对解压出的所有 *.sol 文件计算 shasum 并写入校验文件;
  3. 回到 git 工作区的 contracts 目录,用 shasum -c 对照校验,确保发布到 npm 的包内容与仓库源码逐文件一致,防止打包遗漏或内容漂移。

可升级合约包的联动发布

除主包外,OpenZeppelin 还通过 release-upgradeable.yml 支持可升级(upgradeable)变体的联动发布。该工作流手动触发,state Job 同时 checkout 主仓库与 -upgradeable 仓库,并调用 check-upgradeable.sh 检查可升级变体是否已就绪;publish Job 与 release-cycle 逻辑基本一致(源码中注释为 "copied from release-cycle.yml"),针对 -upgradeable 仓库完成打包、发布与 GitHub Release 创建,唯一差异是显式传入 NPM_TOKEN 并将 NPM_CONFIG_PROVENANCE 关闭,integrity_check 亦针对该变体执行。

关键文件速查

用途 相对路径
发布流程文档 RELEASING.md
主发布工作流 release-cycle.yml
可升级包发布工作流 release-upgradeable.yml
Changesets 配置 .changeset/config.json
状态机计算 state.js
启动 RC 分支 start.sh
版本更新链 version.sh
npm 打包与标签 pack.sh
npm 发布与清理 publish.sh
产物完整性校验 integrity-check.sh
包元数据与脚本入口 package.json
登录后查看全文
WTF-Solidity