用途:按既定流程为 mergify CLI 切出并发布新版本,全程由 .github/workflows/release.yml 驱动,无需在 pyproject.toml 或 Cargo.toml 中改版本号,工作流在构建时写入 tag,不要开“release prep”PR。版本采用 calver:YYYY.M.N(不补零,N 为当月第几次发布,如 2026.10.1);2026 年 10 月前为 YYYY.M.D.N。仓库根目录 RELEASING.md 是人工 runbook。
主要能力与用法:阶段一(安全可重复)先做预检,确认 main 绿、无遗留草稿、查看将发布的提交,然后触发 gh workflow run release.yml(自动选下一个版本),仅在需要指定版本时用 -f tag=... -f target_commitish=<sha>;用 gh run watch <run-id> --exit-status 观察约 5–10 分钟。工作流构建七目标 wheel 矩阵、提取二进制、打包归档与 SHA256SUMS、导出 cli-schema.json、签名并创建带自动生成说明的草稿。随后用 gh release view 校验草稿必须恰好含七个资产(四个 tar.gz、一个 windows zip、SHA256SUMS、cli-schema.json),把草稿 URL 和说明交给用户后停止。阶段二(不可逆、对外)需用户明确同意后执行 gh release edit "$tag" --draft=false --latest,触发发布并推送 PyPI(Trusted Publishing,约 5–10 分钟);说明修改必须在发布前完成。发布后验证发布任务为绿、PyPI 版本正确,并查看 homebrew-tap 的自动 PR(约 20 分钟内生成,仍需人工合并)。
限制与恢复:禁止手动 gh release create 或推 tag,禁止在 Releases UI 点“Draft a new release”,否则发布不可变且资产断言会永久阻断该版本 PyPI 发布。阶段一失败或草稿缺资产时删除草稿重跑,不要手工补;发布后断言失败需删除 release 与 tag 后用同一 tag 重跑阶段一;PyPI 瞬时失败可 gh run rerun <run-id> --failed;版本已被 PyPI 占用则只能发下一个 N。