通过可信发布发布到 npm¶
公开的发布流程是操作上的权威。本页说明仓库和 npm 的机制。
Astryx 通过 GitHub Actions 借助 npm 可信发布(OIDC)发布其公开的 @astryxdesign/* 包。CI 不携带长期有效的 npm 发布 token。每个稳定包都从不可变的发布标签构建,并附带 provenance 发布。
发布顺序¶
- 在当前
main的一个确切提交上运行规范的全范围release-check。该提交还需要通过 Main workflow 的全量单元测试:main 的调度器会在每次对 main 最新提交执行 release-check 时(包括个人触发的)派发一次,大约 15 分钟内,且该提交仍是最新提交。发布负责人也可以在其自己的检查之外,将sha设置为被检查的提交来派发 Main workflow,这样会精确测试该提交;未带sha的派发测试的是开始时 main 的最新提交,不能作为凭据。仅当某个 SHA 同时具备两者且仍处于当前main历史中时,才能基于它进行切版;稳定发布会拒绝缺少两者之一的切版提交。次要版本切版还额外要求发布负责人 Cindy 在分支创建前立即对确切的vX.Y.0明确签字放行;计划内或常设授权永远不能代替该签字。 - 创建唯一的标记分支
release/vX.Y.Z。其版本是切版提交声明的固定组版本。标记和计划会冻结切版 SHA、Changeset 路径与哈希、分支身份以及计划摘要。 - 在该分支上运行
pnpm version-packages。它会根据声明的层级接受已冻结的 Changesets,在已声明的版本下写入变更日志,提升暂存的 codemods,刷新精确的内部固定版本(pins),并仅删除已冻结的 Changesets。它从不选择或提升版本。在 Version Packages PR 合并前,刷新并校验 lockfile。 - 在生成的 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 原生发布:
受信任发布者设置¶
信任按包进行配置。它必须指定 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占位版本,在bootstrapdist-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