跳转至

通过可信发布发布到 npm

公开的发布流程是操作上的权威。本页说明仓库和 npm 的机制。

Astryx 通过 GitHub Actions 借助 npm 可信发布(OIDC)发布其公开的 @astryxdesign/* 包。CI 不携带长期有效的 npm 发布 token。每个稳定包都从不可变的发布标签构建,并附带 provenance 发布。

发布顺序

  1. 在当前 main 的一个确切提交上运行规范的全范围 release-check。该提交还需要通过 Main workflow 的全量单元测试:main 的调度器会在每次对 main 最新提交执行 release-check 时(包括个人触发的)派发一次,大约 15 分钟内,且该提交仍是最新提交。发布负责人也可以在其自己的检查之外,将 sha 设置为被检查的提交来派发 Main workflow,这样会精确测试该提交;未带 sha 的派发测试的是开始时 main 的最新提交,不能作为凭据。仅当某个 SHA 同时具备两者且仍处于当前 main 历史中时,才能基于它进行切版;稳定发布会拒绝缺少两者之一的切版提交。次要版本切版还额外要求发布负责人 Cindy 在分支创建前立即对确切的 vX.Y.0 明确签字放行;计划内或常设授权永远不能代替该签字。
  2. 创建唯一的标记分支 release/vX.Y.Z。其版本是切版提交声明的固定组版本。标记和计划会冻结切版 SHA、Changeset 路径与哈希、分支身份以及计划摘要。
  3. 在该分支上运行 pnpm version-packages。它会根据声明的层级接受已冻结的 Changesets,在已声明的版本下写入变更日志,提升暂存的 codemods,刷新精确的内部固定版本(pins),并仅删除已冻结的 Changesets。它从不选择或提升版本。在 Version Packages PR 合并前,刷新并校验 lockfile。
  4. 在生成的 PR 合并前,清除其上的公开编辑门禁,这样失败的标准会在该 PR 上修复,而不是在事后通过移动发布头来修复。对于补丁版本,按照公开的博客评审规则在 update 配置下,对完整生成的变更日志和草稿 GitHub Release 说明进行自我评分,在 PR 上记录结果,并修复和重新评分每个失败的标准。次要版本需要 Cindy 对变更日志、发布说明和必需的公开博客进行明确的人工编辑审批,并以相同方式记录。然后将生成的 PR 合并到发布分支,运行精确头的分支 CI,并对该精确分支头打标签和发布。拒绝从 main 进行稳定发布。

在该生成的 PR 之后,只有当分支的精确门禁暴露出测试或 harness 缺陷时,分支才接受一个额外类别的提交:一个提交,其稳定 patch id 和精确的改动行摘要与 main 中仍然存在的非合并提交相等,并且其变更文件仅限于非 docsite 测试或 internal/interaction-harness/。它不得更改产品代码、包、Changesets、断言、测试控制、超时、重试或快照。允许该提交的规则必须首先通过正常审查和 CI 合并到 main。如果活动分支早于该规则,发布负责人会在 validate-policy-carry 证明仅策略文件集及其结果内容与已合并到 main 的验证器提交中所审查的分支特定包完全相等之后,追加一次正常的快进策略同步。该包从活动发布头开始。它携带此验证器和范围变更,以及现有的未定范围契约回退——当 GitHub 截断文件列表时,该回退会将每个文件视为已更改;它不携带任何其他后来的 main workflow 或产品工作。该同步不是 pull request,不使用 force 或管理操作,不标记任何检查,也不授予任何发布状态。仅针对 v0.7.12,如果该同步上的正常 CI 证明所携带的验证器不完整,或发现所携带的回退缺少其匹配的工作流契约测试,则可以再进行一次也是最后一次经过审查的快进。其精确包只更改 active-release.mjs、其测试以及 .github/scripts/touched-components.test.mjs;每一行都是从已经合并到 main 的普通 pull request 中精确移植而来;并且 CodeBunny 会在快进之前批准纠正提交的精确头。完整发布门禁会在该头重新运行。不允许第三次同步。然后,修复分支会变基到最终发布头上,其必需的检查在该可信基础上运行。修复本身需要精确头的 CodeBunny 批准以及所有正常的产品和测试通道;合并后,完整精确头的发布门禁会再次运行并且必须通过。任何重试、跳过的检查、管理员合并或手动覆盖都不能替代这些证明。 5. 通过 chore/merge-vX.Y.Z-to-main 将已发布分支的输出压缩合并回当前 main。受信任的验证器要求不可变标签、活动分支头和计划摘要;精确生成的字节和冻结的删除;以及保留每个 cut 后的 Changeset、提交、无关字段和 main 当前的版本声明。分支生命周期文件永远不会落到 main 上。 6. 在一个独立的负责人 PR 中,跨固定组版本、精确的内部固定版本和 lockfile 声明下一计划。已发布版本的补丁后继版本是默认值。仅当负责人明确指定时,才使用次要版本后继。

在切版之后,main 的声明仍然是其未来计划,并且可以独立于已冻结的发布分支而变化。必需的 pull-request lint 不会将其与切版或最新稳定标签进行比较。Canary 发布负责该排序边界:它只从稳定版本之上的一个普通声明进行发布,跳过相等情况,并在低于稳定版本或分裂声明时失败。受信任的合并回写会保留 main 的声明;单独的 next-plan PR 在发布之后推进该声明。

Changesets 与 codemods

功能 PR 通过 pnpm changeset:new 添加常规 Changesets。待处理的 Changesets 不选择发布版本。当包处于 0.x 阶段时,只有在 main 已声明下一个 minor 版本时,[breaking] 工作才被允许;patch 声明会拒绝它。当一个 [breaking] Changeset 处于待处理状态时,将 minor 计划降级为 patch 的 PR 本身也会被拒绝。

未发布变更的核心 codemods 暂存在 packages/cli/assets/codemods/transforms/next/ 中。在 Version Packages PR 期间,pnpm version-packages 会在 changelogs 写入后运行 scripts/promote-codemod-next.mjs。它会把除 README.md 之外的所有暂存条目复制到 transforms/v<declared-version>/,从 next 中清除已提升的文件,并更新注册表。请将这些生成的文件与 changelogs 一起审查。

稳定版与 canary 发布

两个发布路径都位于 .github/workflows/release.yml 中,因为 npm 允许每个包只有一个受信任的 GitHub workflow。

  • Stable: 从不可变的 vX.Y.Z 标签显式触发,携带精确的发布分支、版本、head、标签和计划摘要。它发布 latest。
  • Canary: 最多每小时从 main 的最新提交运行一次,或按需从 main 运行(使用 channel: canary 触发)。仅当声明严格高于最新稳定标签时,它才会将 <declared-version>-canary.g<short-sha> 发布到 canary。它绝不会授权或修改稳定发布状态。

发布步骤使用 pnpm 原生发布:

pnpm publish ./packages/<package> \
  --tag latest --provenance --access public --no-git-checks

受信任发布者设置

信任按包进行配置。它必须指定 release.yml 并允许直接 npm publish。在注册信任之前,新的公共包必须已存在于 npm 上,因此对于每个新包,npm 组织所有者需要在自己的终端中运行一次以下命令(npm 会在浏览器中打开只有所有者才能完成的双因素认证提示):

npm i -g npm@latest
npm --version   # 11.15 or later
npm login --registry https://registry.npmjs.org
node scripts/npm/setup-trusted-publishing.mjs
node scripts/npm/setup-trusted-publishing.mjs \
  --bootstrap --setup-trust --workflow release.yml
  • 默认调用为仅审计模式。
  • --bootstrap 会使用弃用的 0.0.0-bootstrap.0 占位版本,在 bootstrap dist-tag 下声明一个缺失的包名。npm 会将包的第一个版本设为 latest,因此在包的第一个稳定版发布之前,普通安装该包会解析到这个空占位版本。
  • --setup-trust 为 meta/astryx 注册 release.yml,允许直接发布。脚本拒绝 npm 版本低于 11.15 的情况:较旧的 npm 会忽略发布权限,从而创建一个只能暂存发布的发布者,并将所有现有发布者列为冲突。
  • 仅当有意替换现有信任记录时才使用 --replace,切勿用它来清除 npm 11.15 以下版本报告出的冲突。

然后在 npmjs.com 上打开该包的受信任发布者设置(https://www.npmjs.com/package/<name>/access),确认 meta/astryx 的 release.yml 条目允许 npm publish,而不仅仅是 npm stage publish。当脚本无法完成时,同一页面也是手动操作的路径:添加一个 GitHub Actions 发布者,owner 为 meta,仓库为 astryx,workflow 为 release.yml,不设置环境,并允许 npm publish。

npm 会使在 48 小时内未被任何发布验证的新受信任发布者过期。下一个 canary(每小时运行,或从 main 发起的 canary 触发)会发布该包的 canary 并验证它。如果在该时间窗口内没有 canary 发布,请重新创建发布者。

注册表读取可能会在几分钟内持续将刚创建的包报告为缺失。在该时间窗口内重新运行 --bootstrap 会对占位版本得到 409;该名称已被声明,脚本会继续执行信任设置。

仓库固定使用 pnpm 11。CI 的 Node 版本必须内置 npm 11.5.1 或更高版本以支持 OIDC 发布;本地信任设置命令要求 npm 11.15 或更高版本。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx