OxideTerm 发布
通过仓库自有的自动化流程发布 OxideTerm 版本。将用户完成的 GUI 运行视为发布门控，默认不运行 Cargo 测试。
必需的发布输入
在做出发布更改之前，先确定以下值：
- 目标版本。
- 目标通道：
stable、beta或gpui-preview。 - 用户已运行 GUI 应用并批准发布的明确确认。
- 发布说明详细程度：当用户明确要求
minimal、medium或detailed时使用；否则使用detailed。
仅在版本明确无误时推断通道。如果缺少 GUI 批准，请在发布前询问。准备变更日志或进行 dry run 不需要批准。
通道约定
| 通道 | 版本 | 标签 | 变更日志 | 基础说明文件 |
|---|---|---|---|---|
| Stable | X.Y.Z | vX.Y.Z | .github/release-notes/stable-changelog.md | .github/release-notes/stable.md |
| Beta | X.Y.Z-beta.N | vX.Y.Z-beta.N | .github/release-notes/beta-changelog.md | .github/release-notes/beta.md |
| GPUI preview | X.Y.Z-gpui-preview.N | gpui-vX.Y.Z-gpui-preview.N | .github/release-notes/gpui-preview-changelog.md | .github/release-notes/gpui-preview.md |
不要发明其他标签前缀。Native Package 工作流通过其 release_tag 调度输入接收现有标签，并从该标签选择发布说明。
工作流程
1. 检查仓库状态
从 OxideTerm 仓库根目录开始工作。先阅读 AGENTS.md，然后检查：
git status --short --branch
git remote -v
git log -10 --oneline --decorate
在判断标签是否可用之前，先获取发布远程仓库和标签：
git fetch origin --tags
确认分支未落后于或偏离其上游，并检查本地和远程的目标标签：
git rev-list --left-right --count HEAD...@{upstream}
git tag --list <tag>
git ls-remote --tags origin refs/tags/<tag> refs/tags/<tag>^{}
保留用户无关的更改。如果预期的发布范围无法安全分离或分支已偏离，则停止。对于常规发布，当目标标签已存在时停止。仅通过下面显式的已取消发布恢复流程来移动现有标签。
2. 确定变更日志范围
在编写变更日志之前，运行附带的帮助工具：
python3 .agents/skills/oxideterm-release/scripts/release_context.py \
--repo . --channel <channel> --version <version>
优先使用同一通道中上一个可达标签作为基准：
- Stable 与上一个 stable 标签比较。
- Beta 与上一个 beta 标签比较。
- GPUI preview 与上一个 GPUI preview 标签比较。
对于某个通道的首次发布，使用三个通道中最新的可达发布标签作为引导基准。仅当仓库没有更早的可达发布标签时，才使用根提交。这可以确保第一个 beta 或 preview 变更日志的范围限定在实际前一个发布以来的工作，而不是总结整个仓库。
帮助工具会打印出精确的范围、提交和差异摘要。还要检查实际的更改，包括意图中未提交的更改：
git diff <previous-tag>..HEAD
git diff
git diff --cached
不要仅从提交主题推导发布说明。阅读有意义的实现和面向用户的差异。排除机械性的版本号更新、变更日志编辑、仅格式化的变动以及没有发布影响的内部细节。
解析拉取请求和贡献者
对于每个发布通道，在起草说明之前，将确切发布范围内的更改映射到它们的源拉取请求。帮助工具的提交列表排除了合并提交；也要检查合并历史和 GitHub 的提交到 PR 关联，以便合并、压缩和变基合并都能获得归属：
git log --format='%H %s' <previous-tag>..<target-ref>
gh api --paginate repos/<owner>/<repo>/commits/<commit-sha>/pulls \
--jq '.[] | {number, title, url: .html_url, author: .user.login, merged_at, merge_commit_sha}'
gh pr view <number> --repo <owner>/<repo> \
--json number,title,url,author,mergedAt,mergeCommit,commits
维护每个包含的 PR 的编号、URL、作者登录名和实际贡献的工作映射。对多个提交返回的 PR 去重。对照目标历史和差异确认包含关系；仅凭合并日期不能确定发布范围。验证 cherry-picked 更改的原始 PR 来源。完全还原的更改不得作为已发布的功能呈现。
使用 PR 作者，而不是合并它的人或机器人。对于贡献者致谢，排除已确认的项目维护者和机器人账户；不要仅仅因为 GitHub 将其标记为 COLLABORATOR 或 MEMBER 就假定人类贡献者是维护者。当维护者对外部 PR 工作进行了后续修复时，保留对外部 PR 工作的致谢。引用的 issue 编号不是 PR 或其作者的证据。如果 GitHub 查找失败，将未解决的归属保留在工作记录中，并在最终确定发布说明之前解决它；不要将查找失败视为没有贡献。
3. 编写通道变更日志
在选定的变更日志中插入 ## <version> 作为最新条目。标题必须与版本完全匹配，因为 .github/scripts/compose_release_notes.py 使用它来定位条目。标题是提取边界，不一定是已发布发布正文的一部分。
每个版本条目必须按此顺序写成两个完整的语言块（中文在前，英文在后）。组合器会在每个通道的双语发布说明最顶部添加语言跳转链接：
## <version>
### 中文
<中文摘要和章节>
### English
<English summary and sections>
保持两个块在结构上对齐：它们必须以相同的顺序描述相同的结果、限制、验证状态和升级要求。以自然的发布说明语言进行翻译，而不是逐字翻译，并在翻译会降低精确度时保持产品名称、命令、文件名和协议名称不变。不要将英文和中文合并到同一个列表项中。在英文中使用简洁的面向用户的过去时，在中文中使用简洁的已完成动作措辞。保持每种语言的开篇摘要段落在一行内，以便 GitHub Release 编辑器不显示人为的换行。将相关的提交合并为一个结果，避免原始提交标题转储、实现琐事、未经支持的性能声明和未经验证的声明。在每个主要 stable-release 章节标题的两个块中使用一个克制且语义相关的表情符号；不要在每一行上装饰或在一个章节内混合使用多种表情符号风格。
对于 fork 发布，每个语言块必须清晰地将从官方 OxideTerm 上游继承的更改与 fork 实现的更改分开。使用相当于 Upstream changes / 上游更新 和 Fork-specific changes / Fork 自有更新 的明确本地化标题；当所选详细程度需要时，子系统标题可以嵌套在它们下方。将合并或 cherry-picked 的官方工作归类为上游，无论提交作者是谁；将发布 fork 独有的行为归类为 fork 自有。当 fork 修改了上游功能时，在上游下方描述继承的能力，在 fork 自有更改下方描述 fork 的材料差异。如果任一类别在发布范围内没有更改，则明确说明，而不是省略该类别。绝不要让组合的摘要或列表项暗示 fork 撰写了上游工作。
PR 引用和贡献者致谢
遵循 NyaTerm v1.2.12 中的归属模式：PR 引用在其引入的更改旁边，外加专门的贡献者章节。从 OxideTerm 的发布范围推导实际条目。
- 将链接的 PR 编号附加到通过 PR 引入的每个发布说明项，包括维护者撰写的 PR。在中文中使用
（PR [#<number>](<pr-url>)），在英文中使用(PR [#<number>](<pr-url>))。将引用放在相关列表项或功能段落末尾，而不是仅放在贡献者列表或完整变更日志链接中。保持 issue 链接与 PR 链接不同。直接提交没有发明的 PR 编号。 - 当多个 PR 贡献给一个分组项时，在该项中包含所有相关的 PR 编号，仅一次。仅归属每个 PR 支持的结果；当分组会归错作者时，将维护者的独立后续更改分开。对于来自其他仓库的 PR，使用
owner/repo#number限定链接标签。 - 每当发布包含外部 PR 贡献时，在中文块中添加
#### 👥 贡献者，在英文块中添加#### 👥 Contributors，放在更改章节之后和升级说明之前（如果有）。感谢其贡献包含在此版本中的每位外部 PR 作者，包括回归贡献者以及其工作可能不值得独立功能列表项的文档、翻译、构建或打包贡献者。 - 使用其经过验证的 GitHub
@login、对其贡献的简要描述以及链接的 PR 编号，在每个语言块中列出每位作者一次。在两种语言中匹配作者和 PR 引用。通用的感谢或 GitHub 的自动头像条不能替代这些条目。如果识别首次贡献者，请验证之前的仓库贡献；New Contributors列表补充完整的致谢章节。 - 在每个详细级别和每个通道中应用归属。如果验证的范围不包含外部 PR 贡献，则省略贡献者章节，而不是添加空标题。不在发布范围内的 PR 不被视为本版本的新贡献。
贡献者条目示例（用验证的发布数据替换占位符）：
#### 👥 贡献者
感谢以下外部贡献者参与本次更新：
- @<login>：<具体贡献>（PR [#<number>](<pr-url>)）。
#### 👥 Contributors
Thank you to the external contributors to this release:
- @<login>: <specific contribution> (PR [#<number>](<pr-url>)).
将两个示例章节放在各自的语言块中，而不是一起作为第三个双语章节。
发布说明详细程度
对英文和中文块使用相同的级别。这些级别控制覆盖范围和分组，而不是强制性的字数。绝不能为了满足更短的级别而省略破坏性更改、安全边界、升级要求、已知限制或重大兼容性问题。
| 级别 | 要求密度 |
|---|---|
minimal | 仅在用户明确要求时使用。写一个简短的摘要，后面跟着大约 2-5 个高度整合的结果列表项，最多有一两个标题，如果它们能显著提高可扫描性。仅覆盖发布中定义性的用户可见更改和必需的警告。 |
medium | 仅在用户明确要求时使用。写一个摘要、少量有用的章节和分组的列表项，覆盖主要功能、修复和安全或兼容性结果。合并相关的工作流，而不是单独列举每个工作流。 |
detailed | 除非用户明确选择其他级别，否则为默认值。按有意义的子系统或工作流组织说明，并为每个不同的用户可见能力、行为更改、兼容性修复、支持的限制和经过验证的性能或验证结果提供足够的空间，以便在不阅读差异的情况下理解。当它们实质上影响用户理解或使用更改时，包括支持的工作流，但当发布实际更改较少时，不要添加 filler。 |
将这些级别视为覆盖范围和分组指南，而不是固定模板。首先确定完整的事实差异，然后将其整合到所选级别。如果用户只说“编写发布说明”或“准备发布”，则使用 detailed。
应用通道特定的重点：
- Stable： 总结自上一个 stable 标签以来的完整差异。在每个语言块中，从一个简短的发布摘要开始，然后仅使用有用的章节，如
#### ✨ Highlights/#### ✨ 重点更新、#### 🛠️ Fixes/#### 🛠️ 修复、#### 🔒 Security/#### 🔒 安全或#### 🧰 Release Maintenance/#### 🧰 发布维护。强调用户可见的行为和兼容性。组成的 GitHub Release 正文必须以[中文](#中文) | [English](#english)导航开头，然后是完整的### 中文块，然后是匹配的### English块，省略类似# OxideTerm 2.0的产品主标题和类似## 2.0.7的重复版本标题，然后将## 📥 Download for your system、安装提示和链接放在两个语言块之后。 - Beta： 以完整的中英文块总结自上一个 beta 标签以来的差异。说明即将稳定、已更改以及需要验证的工作流。仅当差异或 issue 上下文支持时，才提及已知限制，并在两种语言中都包含它们。
- GPUI preview： 以完整的中英文块总结自上一个 GPUI preview 标签以来的差异。专注于新可测试的原生 UI/运行时工作、对等性、粗糙边缘和具体的测试目标。应用选定的详细程度，同时保持写作以测试为导向，而不是将 preview 说明变成 stable 发布营销。
如果该通道没有更早的标签，请说明哪个前一个发布标签被用作引导基准。
4. 运行仓库版本脚本
始终使用仓库脚本；永远不要手动编辑工作区版本或锁定文件：
python3 scripts/release/bump_version.py <version>
这会验证 SemVer、更新 [workspace.package] 并离线刷新 Cargo.lock。README 徽章会自动显示最新的 GitHub 版本，不需要版本编辑。
5. 执行轻量级发布验证
不要运行 cargo test，
... [已截断]