release-stable

发布稳定版本

稳定版本是大多数人安装的版本，并且是永久的。版本标签一旦推送，就不会移动或删除；版本说明会立即公开，已安装的构建版本也会自动更新到该版本。出错时应在下一个版本中修复，而不是修改当前版本。因此，大部分工作都是在任何内容离开本机之前完成检查。

查找项目的稳定版发布说明

首先，找到项目说明如何发布稳定版本的地方：

• 由版本标签触发的工作流（例如 .github/workflows/stable.yml）。其头部注释通常会列出 步骤、标签模式以及要构建的平台。
• 发布描述文件的 README（例如 releases/README.md），以及 它指向的设计页面。
• 编写发布说明的指南（releases/WRITING.md），其中会决定 版本号。
• 对于仍需手动发布的平台，查找其发布操作手册。项目将发布流程迁移到 CI 时，通常会先用本地命令发布某些平台，而该命令可能会自行编写说明并创建标签。

这些说明会确定标签模式、说明的存放位置和命名方式、由 CI 构建的平台，以及手动发布与 CI 构建这两部分的先后顺序。如果找不到这些说明，请停止并询问如何发布稳定版本。不要自行编造标签、版本号或操作顺序。

开始编写前先检查

1. 将要发布的就是当前工作树的内容。 获取代码和标签，然后确认当前位于主分支，与远程同步且工作树干净。你工作期间主分支可能会有变动，因此在打标签前应再次检查。CI 会使用被打标签提交中的工作流文件进行构建：该提交之后新增的工作流不会为此提交运行。
2. 要打标签的提交在主分支上通过了所有检查。 查看该确切提交对应的 CI 运行记录。如果有作业失败，请停止：列出每个失败作业及其第一个实际错误，并询问是否应先修复主分支。建议先修复，因为稳定版本发布后无法替换。如果仍有作业正在运行，请说明具体是哪几个，并询问是否等待。
3. 版本号尚未被使用。 本地或远程均不存在同名标签（git ls-remote --tags origin v<version>），也不存在同名发布版本（gh release view v<version> 失败）。如果本地有一个从未推送的标签，应特别说明一句：它可能是之前手动发布时留下的，并且必须指向你要发布的提交。
4. 确实有内容可发布。 git log --no-merges <last stable tag or commit>..HEAD 输出不为空。请从说明中指定的发布记录位置查找上一个稳定版提交，而不是从本地标签查找。
5. 发布环境已配置完毕。 工作流所需的环境和其中列出的密钥都已存在（gh api repos/<owner>/<repo>/environments，以及该环境的密钥列表）。如果它们尚不存在就推送标签，会启动一个失败的运行，而且标签无法撤回。

编写说明

对稳定渠道运行 write-release-notes。它会按项目规则选择版本号，并编写说明中指定的描述文件（通常是 releases/<version>.toml）。除遵循这些规则外，还要注意：

• 每个平台的版本都使用同一份描述文件。 手动发布的平台和由 CI 构建的平台应显示相同的说明，因此只需编写一次。
• 仅写出每个平台实际包含的内容。 描述某项功能之前，先确认该功能存在于此版本发布的各个平台上。cfg(windows) 或缺失的平台模块通常是判断依据。仅适用于某个平台的变更应放在该平台的标题下。
• 查看完整提交消息，而非单行摘要： git log --no-merges --format='%h %s%n%b' <last stable>..HEAD，然后查看提交消息未能说明清楚的变更所对应的差异。
• 验证描述文件。 文件可以解析，每个必填字段都已填写且不为空，并且不包含发布工具会拒绝的内容，例如图片或 HTML。

展示，然后发布

向用户展示将要标记的版本、说明和提交。 只有在用户要求发布此版本，并且已看过这些说明，或表示无需审核即可发布时，才进行发布。

1. 只在主分支上提交描述文件，遵循早期发布提交的风格（git log --oneline -- releases/），并推送该分支。这是普通的快进推送，绝不强制推送。
2. 如果有需要手动发布的平台，先处理这些平台，使用项目自己的命令；在需要用户凭据或用户设备的情况下，由用户运行（例如，在 Mac 上构建经过签名的 macOS 版本）。提供准确的命令。如果该命令会创建版本标签，就让它创建，然后检查该标签是否指向描述文件的提交。
3. 再次检查主分支是否未发生变动且仍通过检查。然后为该提交创建标签（如果尚未标记），并且只推送该标签：git push origin v<version>。绝不使用 --force，也绝不使用 --tags，后者还会推送所有其他本地标签。

监控并验证

1. 找到标签推送启动的运行（gh run list --workflow <file>），并监控它（gh run watch <id>）。
2. 运行成功后，检查发布（gh release view v<version>）。它不是预发布版本。发布包含所有由 CI 构建的平台包、签名和更新清单。发布正文就是说明。
3. **检查“最新版本”指向何处。**已安装的构建版本通常通过最新发布别名读取其更新源，因此请检查该别名是否解析为最新的稳定版本（gh release view --json tagName，不带标签）。较旧版本线上的补丁不得成为最新版本。如果标记了错误的发布版本，请先说明，再进行更改：更改它会影响所有已安装构建版本可获取的更新。
4. 通过应用读取的别名获取更新清单，并检查清单是否指定了此版本及一个可下载的软件包。
5. 报告运行和发布的链接、版本和构建号、手动发布部分的产物，以及检查发现的任何问题。

如果构建失败

标签不能变动，因此无需更改标签即可修复故障。

• 暂时性故障（运行器故障、网络超时）：重新运行失败的作业（gh run rerun <id> --failed）。使用相同的标签和说明重新构建，并且发布步骤只能替换该次运行自己的文件。
• 缺少密钥或环境：由用户创建，然后重新运行失败的作业。无需新建标签。
• 需要修复代码的故障：无法从此标签构建此版本。建议使用修复后的提交发布下一个补丁版本，并为其创建独立的描述文件。询问用户失败版本的手动发布部分是否已经上线：如果已经上线，那么在补丁版本发布之前，各平台版本会有所不同，补丁版本的说明应写明修复内容。