quiche GitHub Draft Release 自动化指南：从版本提交哈希到草稿发布

• 网络
• 通信
• 后端

本篇指南讲解 quiche 仓库中如何通过.opencode/skills/quiche-draft-release技能，仅凭一个「修改了quiche/Cargo.toml版本的提交哈希」或一个已存在的 release tag，自动完成 GitHub draft release 的创建。文中将结合技能定义 SKILL.md、辅助脚本 create-draft-release.sh 与发布流程文档 RELEASING.md 的源码级细节，说明 dry-run 预检、release notes 编写规范、gh release create草稿创建与验证的完整链路。读完你既能直接复跑这套发布流程，也能理解脚本「以提交为真相来源、容错 tag 缺失」的设计原理。

为什么需要这套发布技能

quiche 是一个包含多个 workspace crate 的仓库（见 Cargo.toml：quiche、tokio-quiche、h3i、qlog、octets等），其中只有quichecrate 本身通过 GitHub Releases 提供 release notes。仓库采用 pre-1.0 版本号，X.Y.Z中 bump 次版本号Y等价于一次破坏性大版本发布，bump 补丁号Z等价于次要发布（RELEASING.md）。

发布流程中的关键约束是：quiche 的 release tag 是在 release PR 合并之后才创建的，因为 GitHub 不支持 fast-forward 方式的 PR 合并（SKILL.md）。合并时 PR 提交会被 rebase，因此发布提交的哈希在合并前后可能变化；tag 必须在合并完成后，指向最终的合并提交创建。这导致创建 draft release 时存在一个时间窗口——release tag 尚不存在，而版本提交哈希已经确定。

于是本技能确立了一条原则：以「修改了 quiche 版本的提交哈希」为真相来源（source of truth），当 tag 尚不存在时，让gh release create通过--target <commit>直接指向该提交；若 tag 已存在，则传入 tag 或哈希皆可（SKILL.md）。

输入参数（Inputs）

创建 draft release 只需要两类输入（SKILL.md）：

• 必填：release ref。二选一：
  • 将quiche/Cargo.toml版本改为待发布版本的提交哈希（release commit hash）；
  • 指向该提交的既有 release tag，例如0.29.1。
• 可选：release 标题 emoji。若未指定，则选择与既有 quiche release 风格一致的 emoji（quiche 0.30.0 的标题示例为🩹 0.29.1）。

若 release ref 缺失或存在歧义，技能要求先提出一个简短的澄清问题，而不是自行猜测。

Helper 脚本行为（源码级解析）

整个技能的核心逻辑集中在辅助脚本 create-draft-release.sh 中，其关键行为与源码一一对应：

1. 解析 release ref 并读取版本号。脚本首先判断传入的 ref 是否为既有 tag（L116-L123），随后用git rev-parse --verify "$release_ref^{commit}"解析出提交（L125-L126），再通过git show "$commit:quiche/Cargo.toml"读取该提交处的version字段（version_from_commit函数，L44-L49）。如果传入的 tag 名与读取到的版本号不一致（例如 tag0.29.1指向的提交版本是0.30.0），脚本会直接报错拒绝。

2. 校验提交确实 bump 了版本。脚本解析该提交的第一父提交（$commit^），读取父提交的 quiche 版本，若与当前版本相同则报错commit ... does not bump quiche/Cargo.toml version（L136-L143）。这保证了你不会在错误的提交上创建 release。

3. 推断上一个 release tag。脚本用git tag --merged "$commit" --sort=-version:refname --list '[0-9]*.[0-9]*.[0-9]*'列出合并进该提交的 semver 风格 quiche tag，按版本号降序取第一个不等于当前版本者作为previous_tag（L145-L158），用于生成 compare 链接https://github.com/$repo/compare/$previous_tag...$version。注意此处列表模式[0-9]*.[0-9]*.[0-9]*天然排除了带 crate 前缀的 tag——这正对应 quiche 自身 tag 不带 crate 名的历史约定（详见下文「tag 命名约定」）。

4. 处理 tag 缺失场景。若版本号对应的 tag 尚不存在，脚本追加--target "$commit"参数让gh release create指向该提交；若 tag 存在，则校验其指向的提交与解析出的 release commit 一致，不一致即报错（L163-L174）。

5. 只创建草稿。最终命令固定携带--draft（L176-L181），且创建前会用gh release view检查同版本 release 是否已存在，已存在则拒绝（L211-L213）。

脚本还校验运行环境：必须位于 quiche git 仓库内（git rev-parse --show-toplevel），且系统装有git与 GitHub CLIgh（L109-L114）。--repo参数默认为cloudflare/quiche，可通过--repo OWNER/REPO覆盖。

tag 命名约定

workspace 级 release 配置默认 tag 前缀为{{crate_name}}-（见 Cargo.toml），例如tokio-quiche-0.6.0；而quichecrate 自身通过[package.metadata.release] tag-prefix = ""（quiche/Cargo.toml）去掉了前缀，因此 quiche 的 tag 就是纯版本号如0.29.1。这一历史约定正是本技能推断 previous tag、校验输入 tag 时直接使用裸版本号的前提。

完整工作流（Workflow）

技能定义的七步工作流（SKILL.md）如下：

Step 1：Dry run 预检。先以--dry-run运行脚本，确认推断结果无误：

./.opencode/skills/quiche-draft-release/scripts/create-draft-release.sh --dry-run <release-ref>

Step 2：解读 dry-run 输出。输出会给出 release ref、解析出的提交、版本号、上一版本/上一 tag、compare 链接、tag 是否已存在、标题与 notes 文件路径，以及将要执行的完整gh命令（L189-L206）。据此确认版本、上一 release tag、compare 范围与 tag 存在状态。

Step 3：按 RELEASING.md 规范编写 release notes（仅针对 quiche crate）。核心规范（RELEASING.md）包括：

• 不用原始提交列表——提交信息往往混杂内部重构、测试修复、clippy/format 修复等对用户无意义的内容；
• 只列重要的、用户可见的变更，每条配简短描述；
• 破坏性变更与安全修复必须明确标注，这两类最需要用户关注；
• 对破坏性变更，说明应用方需要做哪些改动，方便用户快速行动；
• 对新增公共 API 可附版本化的docs.rs链接；
• 忽略无关 workspace crate 的 release 提交、格式修复、clippy、纯测试改动以及无用户可见影响的内部重构（SKILL.md）。

Step 4：将 notes 写入临时文件。例如/tmp/opencode/quiche-release-<version>.md。

Step 5：创建前确认。除非用户明确要求跳过确认，否则先展示将要执行的完整gh release create命令，征求确认。

Step 6：创建草稿 release：

./.opencode/skills/quiche-draft-release/scripts/create-draft-release.sh \ --title "<emoji> <version>" \ --notes-file /tmp/opencode/quiche-release-<version>.md \ <release-ref>

Step 7：创建后验证：

gh release view <version> --repo cloudflare/quiche \ --json tagName,name,isDraft,isPrerelease,url

GitHub 的 draft release URL 经常呈现为untagged-*形式，这并不能直接判断 release 归属；应以gh release view返回的tagName为准来确认草稿关联到了预期的版本（SKILL.md）。脚本在创建成功后也会自动执行一次等价的gh release view输出 JSON 供核对（L217-L219）。

实战示例

对版本提交做 dry run：

./.opencode/skills/quiche-draft-release/scripts/create-draft-release.sh \ --dry-run f0c7193c3

用已存在的 tag 做 dry run：

./.opencode/skills/quiche-draft-release/scripts/create-draft-release.sh \ --dry-run 0.29.1

从提交哈希创建草稿：

./.opencode/skills/quiche-draft-release/scripts/create-draft-release.sh \ --title "🩹 0.29.1" \ --notes-file /tmp/opencode/quiche-release-0.29.1.md \ f0c7193c3

从已存在的 tag 创建草稿：

./.opencode/skills/quiche-draft-release/scripts/create-draft-release.sh \ --title "🩹 0.29.1" \ --notes-file /tmp/opencode/quiche-release-0.29.1.md \ 0.29.1

两种创建方式在脚本内部走向相同：前者因 tag 尚不存在会带上--target f0c7193c3，后者直接使用既有 tag。当前仓库quiche/Cargo.toml中版本为0.30.0（quiche/Cargo.toml），实际发布时以上示例中的版本号与哈希应替换为对应发布的实际值。

与其他发布环节的衔接

本技能只负责「GitHub draft release」这一环节，上游的版本决策与下游的发布发布均有独立的流程文档支撑（RELEASING.md）：

• 版本类型决策：可用cargo semver-checks -p <crate>检测 API 破坏；即便检测不到 API 变更，重大行为变化也可能需要 bump 次版本（RELEASING.md）。
• 依赖检查：用cargo package -p <crate>确认 crate 能在仓库外构建，避免发布后无法发布到 crates.io（RELEASING.md）。
• release 分支与 PR：git checkout -b release-x.y.z后用cargo release --no-push --no-publish --no-tag创建发布提交并开 PR；因 GitHub 会 rebase，故用--no-tag推迟打 tag（RELEASING.md）。
• PR 合并后打 tag：git tag <crate>-<version>，如git tag tokio-quiche-0.6.0；quiche 自身例外，tag 不带 crate 名（RELEASING.md）。tag 一旦创建，本技能的 dry-run 与创建命令便可改用 tag 作为 release ref。
• 发布到 crates.io：cargo publish -p <crate>，随后确认 crates.io 与文档站点构建成功（RELEASING.md）。

边界与禁止事项

技能明确划定了操作红线（SKILL.md）：

• 不要手动创建或移动 git tag——tag 的创建时机在 release PR 合并之后，由维护者按 RELEASING.md 流程单独执行，本技能不承担此职责；
• 不要发布 release——始终保持 draft 状态，是否转正式发布由人工决策；
• 不要用本技能为quiche之外的 workspace crate 创建 release（tokio-quiche、h3i、qlog、octets等均有各自的发布节奏）；
• 不要覆盖或编辑已存在的 GitHub release，除非用户明确要求。

小结

quiche draft release 自动化的精髓在于「以版本提交哈希为真相、以 tag 为可选项」：脚本从提交处读取quiche/Cargo.toml的版本、校验版本确实发生 bump、从已合并的 semver tag 推断对比范围，并在 tag 缺失时自动回退到--target <commit>，全程仅产出 draft。配合 RELEASING.md 的「仅列用户可见变更、标注破坏性与安全修复」的 notes 规范，这套流程把发布中最易出错、最繁琐的部分收敛成一个可 dry-run、可确认、可验证的命令，值得作为同类 Rust workspace 项目发布自动化的参考模板。

• 网络
• 通信
• 后端