发布工程策略

五项策略规定 apothem 的发布方式。

1. 语义化版本Copy Anchor Link

项目按照语义化版本 2.0发布。版本号采用 MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD] 的形式。

候选标签采用 vX.Y.Z-rc.N（发布候选）或 vX.Y.Z-alpha.N / vX.Y.Z-beta.N（早期访问）格式。

2. 发布标签Copy Anchor Link

每次发布都会在 main 上落地一个形如 vMAJOR.MINOR.PATCH 的经签名 git 标签。该标签触发 .github/workflows/release.yml，由它执行构建、签名、生成 SBOM 和 SLSA-3 出处溯源，并发布 GitHub Release 页面。

标签约定：

• 格式——严格为 vMAJOR.MINOR.PATCH。不带 release- 前缀，不带 -final 后缀。
• 附注——每个标签都是附注标签（git tag -a -s），并在标签消息中携带发布说明摘要。
• 签名——每个标签都经 GPG 签名。发布工作流还会为每个工件生成 Sigstore 无密钥 cosign 签名，并生成一份 SLSA-3 出处溯源记录，两者均附加到 GitHub Release 页面。

发布模型：追加式Copy Anchor Link

发布是追加式的。每次发布在 main 上添加一个提交和一个标签；main 绝不会被强制推送，任何已发布的标签、GitHub Release 或 npm 版本都不会被删除、移动或复用。每个发布都保留其标签、其 GitHub Release 和其 npm 版本，所有发布都保持已发布状态。npm 版本不可变：已发布的 name@version 永远无法被替换，已被撤销发布的版本号也永远不能再次使用。固定版本的安装和可复现构建依赖于每一个已发布的标签。发布周期和发布恢复这两份操作手册都遵循此模型。

仓库的发布门面规则（贡献者说明中的 Release Facade 一节）阐明了本模型。其仅限当前版本的要求（在 freshness-facade 规则中有镜像）适用于公开表面上的说法。它不限制哪些发布仍保持已发布状态。

3. 弃用策略Copy Anchor Link

当前的公开支持线是最新发布的次版本。当项目存在多个公开次版本时，SECURITY.md 中的支持版本矩阵是任何额外的、仅限关键修复的支持窗口的权威来源。

弃用节奏：

• 公告——被弃用的符号或行为会在弃用落地的那次发布的 CHANGELOG.md ### Deprecated 部分中公告。发布说明会同步该弃用公告。
• 宽限窗口——被弃用的符号在移除前至少保留一个完整的次版本周期。
• 移除——移除在 MAJOR 递增中落地。每个被移除的符号都带有一行 CHANGELOG.md ### Removed 条目，以及操作指南下的一条迁移指南条目。

运行时下限Copy Anchor Link

Apothem 声明了两个运行时下限：pyproject.toml 中的 requires-python = ">=3.10"，以及 package.json 中的 "engines": {"node": ">=18"}。

• 每个已声明的下限都经过测试。 Python 下限在 CI 的 quality 矩阵和 CI Matrix 工作流中运行。npm Shim 工作流在 Node 下限及其后的每个 LTS 主版本上运行 npm 垫片：它检查缺失前置条件时的错误、node bin/apothem.mjs --version、在隔离的主目录中进行的一次试运行安装，以及通过 npx 运行的打包后 tarball。未经测试的运行时不会被声明。
• 生命周期终止会被披露。 当某个仍是已声明下限的运行时到达上游生命周期终止时，安装指南会说明这一点，并列出应优先选用的版本。Python 3.10 于 2026-10-01 到达生命周期终止；Node.js 18 和 20 分别于 2025-04-30 和 2026-04-30 到达。这三者仍然是受支持的下限。
• 提高下限属于一次弃用。 它遵循上述节奏：先在 ### Deprecated 下发布公告，再经过至少一个完整的次版本周期，期间旧下限仍保持受测试，然后由提高该下限的那次发布记录这一变更。requires-python、engines.node、安装器的版本探测以及 CI 矩阵在那次发布中一同变更。

4. 破坏性变更策略Copy Anchor Link

破坏性变更需要：

1. 一个 RFC 问题——针对 rfcs 问题标签提出，描述该破坏性变更、迁移路径和回滚策略。
2. 30 天评论窗口——RFC 在合并前至少保持开放 30 天。当反馈有此需要时，维护者可以延长该窗口。
3. 一次 MAJOR 递增——落地该破坏性变更的那次发布会递增 MAJOR 部分。
4. 一份迁移指南——该变更随附一条操作指南条目，引导操作者完成迁移。

5. 回滚策略Copy Anchor Link

如果某次发布出现了阻碍采用的回归：

1. 还原——在 main 上还原有问题的提交。
2. 向前修复发布——一次后续发布以 vMAJOR.MINOR.PATCH+1 落地，携带该还原以及任何增量修复。先前有问题的发布不会从 GitHub Releases 中删除，其 npm 版本保持已发布状态（npm 版本不可变），并用 npm deprecate 加以标记。CHANGELOG.md 中的一条 ### Yanked 注记记录该情况，使可复现构建保持锚定。
3. 沟通——回滚会附带一条安全公告通知（当涉及安全时）或一个为该事件置顶的 GitHub 问题（当涉及可靠性时）。

另请参阅Copy Anchor Link

• CHANGELOG.md——权威的发布账本。
• SECURITY.md——支持版本矩阵和报告渠道。
• cicd-pipeline.md——把关每次发布的各类 CI 检查。
• deployment-checklist.md——每次发布的生产就绪扫查。