release

发布版 — 分层兼容性与发布工作流

对于 Cull 仓库，请使用 $cull-release；Cull 仓库强制执行的状态、制品、更新程序和 Homebrew 门禁比此通用工作流更严格。

这是一个由配置驱动的发布编排器。具体机制位于 scripts/release.py （仅使用标准库，并经过单元测试）；本文档是你（或 Agent）需要遵循的工作流。 请阅读 reference/config-schema.md 了解 release.config.json，并阅读 reference/standards.md 了解每个步骤存在的原因。

范围说明： 已在 Tauri + Rust + SvelteKit 仓库（Cull）上进行参考测试。 其他技术栈可通过配置支持，但尚未验证。在你确信之前，将新技术栈的首次运行视为试运行（见下文“试运行”）。

何时使用

用户说“发布”“发出去”“切一个版本”“提升版本号”“为版本打标签”“更新变更日志/COMPATIBILITY”时使用。仓库根目录必须有 release.config.json（从 templates/release.config.json.tmpl 创建）。

思维模型——你的公共 API 就是你声明的接口

只有声明了承诺保持正常运行的内容，版本才有意义。release.config.json → surfaces[] 就是这份声明；每个接口都有一个层级（experimental → preview → stable）和一个兼容性模式。只有 stable 接口才带有承诺。破坏 stable 接口时必须进行主版本升级——引擎会强制执行此要求。（标准说明：见 reference/standards.md。）

命令

/release <patch|minor|major> — 执行以下步骤。在不熟悉的仓库上，先进行试运行（见下文）。用户要求“解释”时，将每个步骤的原因扩展为 reference/standards.md 中的简短说明。

步骤

1. 前提条件。 已检出配置的 releaseBranch（默认为 main；如果设置了 worktree，则在其中检出），工作区干净且与 origin 同步。否则应明确中止。 — 原因：发布标签必须指向已知良好且已推送的代码树。

2. 版本。 python3 scripts/release.py --config <cfg> plan <kind> 会打印新版本和标签，并断言当前各版本文件中的版本一致。显示 旧版本 → 新版本。 — 原因：SemVer 计算；在 0.x 阶段，次版本号变更允许破坏兼容性（pre-1.0）。 [[Semantic Versioning (SemVer)]]

3. 就绪门禁。 运行 cfg.gate，然后运行每个 cfg.extraGate[]。所有命令都必须以 0 退出（fmt、clippy、测试、许可证审计、生产构建、黄金契约测试）。失败时阻止发布。 — 原因：这是一次生产就绪审查。 [[Production Readiness Review]]

   • TODO（暂缓）：cargo-deny / cargo-audit / SBOM。先列出，不要强制执行。

4. 变更日志。 收集自上一个标签以来的提交主题（git log <lastTag>..HEAD --format=%s）并起草一个章节 — 引擎的 draft_changelog 会将它们归类为 Added/Changed/Fixed（Keep a Changelog）。插入到 CHANGELOG.md 顶部下方；手动整理面向用户的条目。 — 原因：人们会阅读变更日志；约定式提交可作为起草素材。 [[Keep a Changelog]]

5. 兼容性审查。 打开 cfg.compatibility.path（COMPATIBILITY.md）。检查：

   • 是否有任何接口的稳定性级别发生变化？（更新 Surfaces 表）
   • 是否有新的弃用项？（添加一行：项目 / 弃用版本 / 可移除版本 / 替代项）
   • 此变更是否会破坏 stable 接口？ 如果是，必须提升 major 版本 — 使用 major 重新运行，否则此次发布无效。（由 enforce_bump 强制执行。）标注“上次更新：<新版本>（<日期>）”。 — 原因：接口级别和弃用窗口能让你在不误导用户的情况下逐步演进。 [[Kubernetes API Deprecation Policy]]

6. 升级版本并提交。 python3 scripts/release.py --config <cfg> bump <kind> 会写入所有版本文件；刷新 cfg.lockfiles（例如运行 cargo update -p <crate> 或进行构建）。提交 chore(release): v<new>，包含 CHANGELOG 和 COMPATIBILITY。

7. 打标签并推送。 运行 git tag v<new>，并推送标签（→ 仓库的发布工作流）和分支。首次发布前，确认标签触发器已配置（grep -A3 '^on:' .github/workflows/*.yml）。

8. 报告。 打印标签、发布工作流 URL，以及自上一个标签以来已关闭的问题（如果设置了 cfg.issueTracker，例如 bd）——这些就是发布说明。

试运行

没有 --dry-run 标志 — 试运行就是完成步骤 1–5，但不进行任何修改：运行 python3 scripts/release.py --config <cfg> plan <kind>（纯操作：打印版本和标签，不写入任何内容），并可选择运行 cfg.gate 检查就绪情况。 不要运行 bump，不要提交，也不要打标签。bump 子命令是唯一会写入内容的引擎命令（仅写入版本文件）；提交、打标签和推送都是你在步骤 6–7 中执行的 git 操作，不属于引擎操作。

逐步完善契约与模式

就绪门禁会运行黄金测试/契约测试（cfg.extraGate）。先从一个测试开始（数据库往返测试），然后添加导出和 API 契约测试。参见使用方仓库的 docs/CONTRACTS.md 和 reference/standards.md。[[Pact — Consumer-Driven Contract Testing]]