发布恢复操作手册
在追加式发布模型下，针对执行途中失败的发布逐阶段给出的恢复流程，不改写已发布的历史。
当 ahmed-g-gad/apothem 的一次 vX.Y.Z 发布中途失败时，本操作手册将其恢复到可用状态。它遵循与发布周期操作手册相同的发布模型：一种追加式模型。每次发布在 main 上添加一个提交和一个经签名的附注标签；标签推送会运行发布工作流和 npm 工作流。任何内容都不会被强制推送，main 上的历史绝不会被改写。
已发布的历史是永久的。项目已发布的每个发布标签、GitHub Release 和 npm 版本都保持已发布状态。npm 版本不可变：已发布的 name@version 永远无法被替换，已被撤销发布的版本号也永远不能再次使用。因此，恢复通过一个新的补丁发布向前推进；它不会删除或重新指向用户可能已经安装的任何内容。
1. 阶段分类
| 阶段 | 操作 | 失败模式 | 恢复路径 |
|---|---|---|---|
| 1 | 将发布提交落地到 main（发布周期操作手册的 §2.1） | 发布提交上的 CI 失败 | 在 main 上用另一个提交向前修复；CI 变绿之前不要打标签 |
| 2 | 推送经签名的附注标签 | 推送被拒绝，或标签未签名或位于错误的提交上 | 见下文 §2 |
| 3 | release.yml 构建、签名并发布 GitHub Release | 某个作业失败，或产物缺失 | 见下文 §3 |
| 4 | publish-npm.yml 发布 @ahmed-g-gad/apothem（在同一次标签推送上运行） | 发布失败 | 见下文 §3 |
| 5 | Pages 与仓库元数据 | 站点或元数据过时 | 见下文 §3 |
每个恢复操作都是幂等的。在干净状态上运行它不产生任何效果；在部分完成的状态上运行它会恢复预期的阶段后状态。
2. 标签恢复
诊断标签：
git fetch origin --tags
git ls-remote origin refs/tags/vX.Y.Z
git cat-file -t vX.Y.Z # "tag" for an annotated tag
git tag -v vX.Y.Z # signature check如何处理取决于是否已从该标签发布了任何内容：
-
尚未发布任何内容（发布工作流在其发布作业之前就已失败，且
publish-npm.yml没有发布）：删除该标签，并用-a -s对同一提交重新打标签。git push --delete origin vX.Y.Z git tag -d vX.Y.Z git tag -a -s vX.Y.Z -m "vX.Y.Z" <release-commit-sha> git push origin vX.Y.Z -
已发布任何内容（带产物的 GitHub Release，或 npm 版本）：绝不移动、删除或复用该标签。用
vX.Y.(Z+1)向前修复。
标签名绝不会被复用于另一个提交。
3. 发布者恢复
每个发布者都单独重试：
| 表面 | 诊断 | 恢复 |
|---|---|---|
| 发布工作流 | gh run view <run-id> --log 会指出失败的作业 | gh run rerun <run-id> --failed。在 Check the plugin version changed with the plugin 处失败意味着版本号没有提升：参见发布周期操作手册的失败表 |
| GitHub Release | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | 重新运行 publish GitHub Release 作业；它会编辑现有的发布，并使用 --clobber 重新上传产物 |
| npm | npm view @ahmed-g-gad/apothem version 与 npx @ahmed-g-gad/[email protected] --version | 在确认该包的 npm 受信任发布之后，为 vX.Y.Z 重新运行 publish-npm.yml（gh workflow run publish-npm.yml --field tag=vX.Y.Z）。如果该版本已在注册表上，工作流会跳过发布，因为 npm 版本不可变 |
| Pages | gh run list --workflow=publish-static-site.yml --limit=1 与 curl -sSI https://apothem.ahmedgad.com/ | 重新运行 publish-static-site.yml；验证 CNAME 仍解析到 ahmed-g-gad.github.io |
| 仓库元数据 | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | 原地修补描述、主页和主题；绝不重新创建仓库 |
4. 回滚
有问题的发布通过发布其修复来回滚，而不是通过移除它：
-
在
main上还原引起问题的提交（一个普通的还原提交）。 -
按照发布周期操作手册切出
vX.Y.(Z+1)。 -
标记有问题的版本：在其
CHANGELOG.md部分中添加一条### Yanked说明，编辑其 GitHub Release 说明使其指向修复，并在 npm 上将其弃用：npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
有问题的标签、GitHub Release 和 npm 版本保持已发布状态，因此固定版本的安装和可复现构建会继续正常解析。将此次回滚记录为一次发布事件。
5. 发布门面规则
仓库的发布门面规则（贡献者说明中的 Release Facade 一节）阐明了上述追加式模型：所有已发布的标签、GitHub Release 和 npm 版本都保持已发布状态。其仅限当前版本的要求适用于公开表面上的说法。本操作手册绝不删除或改写已发布的标签、GitHub Release 或 npm 版本。
6. 交叉引用
- 发布流程：发布周期操作手册。
- 发布策略：发布工程策略。
- 标签对象及如何逐一验证：SECURITY.md 的发布签名部分。
- Pages 配置：
site/content/docs/runbooks/pages-enablement.mdx。