# 📦 Release 工作流
本文档描述 Garrison 项目的发布流程,遵循规则 18/19/21 + project_memory 安全/质量门禁要求。
## 📋 目录
- [发布流程图](#-发布流程图)
- [版本规范](#-版本规范)
- [发布前检查清单](#-发布前检查清单)
- [本地预检查](#-本地预检查)
- [发布步骤](#-发布步骤)
---
## 🔄 发布流程图
<div align="center">
<img src="assets/release-flow.svg" alt="发布流程" width="800">
</div>
```mermaid
flowchart TD
TagPush["开发者本地推送 tag<br/>git push origin v0.7.1"] --> Stage1
subgraph Stage1["阶段 1: 前置检查(并行,任一失败阻断)"]
Lint["lint-check<br/>fmt + clippy"]
Test["test-check<br/>lib + E2E"]
Sec["security-check<br/>cargo deny"]
Doc["doc-check<br/>cargo doc 零警告"]
end
Stage1 --> Stage2["阶段 2: version-consistency<br/>Cargo.toml == CHANGELOG == tag<br/>提取 CHANGELOG body"]
Stage2 --> Stage3["阶段 3: publish-crates-io<br/>cargo publish"]
Stage3 --> Stage4["阶段 4: github-release<br/>创建 GitHub Release<br/>(crates.io 失败则不创建)"]
Stage4 --> Stage5["阶段 5: verify-release<br/>验证 GitHub Release + crates.io"]
Stage5 --> Done["✅ 发布完成"]
```
> **注意**:tag 由开发者本地推送触发,CI 不创建 tag。`workflow_dispatch` 输入的 `version` 通过环境变量传递(防 shell 注入)。
## 📏 版本规范
- **Git tag 格式**:`v{Major}.{Minor}.{Patch}`(如 `v0.7.1`),符合 semver
- **Cargo.toml `[package].version` 字段**:`{Major}.{Minor}.{Patch}`(如 `0.7.1`)
- **docs/CHANGELOG.md**:每次发布新增 `## [{version}] - {YYYY-MM-DD}` 章节
- **规则 29 例外**:Cargo.toml 的 `[dependencies]` 版本用 `x.x` 格式(无 patch 段),但 `[package].version` 仍用 `x.x.x`(与 crates.io / git tag 一致)
- **Workspace 成员**:`macros/Cargo.toml` 与 `examples/Cargo.toml` 均为 `version.workspace = true`,无独立 version 字段。`bump-version` 子命令的 sed 只替换首个 `^version = ".+"` 行(即主包 `[package].version`),**不会**触及主 `Cargo.toml` 的 `[workspace.package].version`——后者需手动同步,否则 workspace 成员版本与主包脱节
## ✅ 发布前检查清单
发布前必须完成以下检查(任何一项失败都阻断发布):
| 格式化 | `cargo fmt --all -- --check` | 无差异 | 规则 18 |
| Clippy | `cargo clippy --features full --lib --tests -- -D warnings` | 0 warnings | 规则 18 |
| Lib 测试 | `cargo test --features full --lib` | 0 failed | project_memory |
| E2E 测试 | `cargo test --features full --test '*'` | 0 failed | project_memory |
| 文档构建 | `RUSTDOCFLAGS="-D warnings" cargo doc --features full --no-deps` | 0 errors(`scripts/release.sh` 第 6 步执行的即此命令) | project_memory |
| 安全审计 | `cargo audit` | 0 CRITICAL | 规则 19 |
| 依赖审计 | `cargo deny check` | 0 failures | 规则 18 |
| 版本一致性 | `scripts/release.sh check-version` | Cargo.toml == CHANGELOG,tag 不存在 | 规则 21 |
> **文档内链漂移只有发布链路能发现**:`ci.yml` 的 doc job 跑的是不带 `-D warnings` 的
> `cargo doc --no-deps --features full`,rustdoc 的 `unresolved link` / `links to private item`
> / `redundant explicit link target` 在 CI 上表现为警告而被忽略;一旦改动了 `///` / `//!`
> 中的内链(新增类型、移动模块、把内部项写进公开文档),发布前必须本地跑上表那条命令。
## 🔍 本地预检查
在打 tag 前运行本地预检查脚本:
```bash
# 完整预检查(所有检查项)
./scripts/release.sh precheck
# 仅检查版本一致性
./scripts/release.sh check-version 0.7.1
# 生成 changelog 段落(从 git log 提取,可指定版本号)
./scripts/release.sh gen-changelog v0.7.0..HEAD 0.7.1
# 可复现构建验证(两次独立编译逐字节比对)
scripts/verify_reproducible_build.sh
```
### 可复现构建(Reproducible Build)
`scripts/verify_reproducible_build.sh` 对 garrison 库做两次独立编译,比对
`libgarrison.rlib` 的 sha256 是否逐字节一致。与 Release 资产上的
**Artifact Attestations(构建溯源)互补**:attestation 回答"产物是否来自本仓库
CI",可复现验证回答"相同输入是否产出相同字节"——下游可用两者交叉核验所获产物。
前提与边界:
- 可复现性以**同 rustc 工具链 + 同 Cargo.lock** 为前提(`--locked --frozen` 强制);
工具链或依赖版本变化后需重新验证(CI `security.yml` 的 `reproducible-build`
job 在每次 PR 上持续锚定)。
- 构建输入固定:`SOURCE_DATE_EPOCH` 固定时间戳、`--remap-path-prefix` 消除本地
绝对路径差异;两次构建间仅清理 garrison 自身指纹与产物(依赖缓存复用)。
- 脚本含负对照语义:任何源码变化必然改变哈希(已验证),不存在"构建未发生"的
假阳性通过。
## 🚀 发布步骤
### 1. 更新版本号
使用脚本或手动编辑 `Cargo.toml`:
```bash
./scripts/release.sh bump-version 0.7.1
```
或手动编辑:
```toml
[package]
version = "0.7.1" # 旧值 0.7.0 → 新值 0.7.1
```
### 2. 更新 CHANGELOG.md
在 `## [Unreleased]` 之后新增版本章节:
```markdown
## [0.7.1] - 2026-07-20
### Security
- 修复 XXX 漏洞(CVE-XXXX-XXXXX)
### Added
- 新增 XXX 功能
### Changed
- XXX 行为变更
### Fixed
- 修复 XXX bug
```
可使用 `./scripts/release.sh gen-changelog v0.7.0..HEAD 0.7.1` 自动生成 oneline 草稿,再人工分类到上述章节。
### 3. 运行本地预检查
```bash
./scripts/release.sh precheck
```
所有检查通过后进入下一步。
### 4. 提交版本变更
```bash
git add Cargo.toml docs/CHANGELOG.md
git commit -m "chore(release): bump version to 0.7.1"
```
### 5. 打 tag
```bash
git tag -a v0.7.1 -m "Release v0.7.1"
git push origin v0.7.1
```
### 6. 触发 CI 发布工作流
tag push 会自动触发 `.github/workflows/release.yml`,包含 5 个阶段 8 个 job:
1. **lint-check**(阶段 1 并行):fmt + clippy
2. **test-check**(阶段 1 并行):lib + E2E 测试
3. **security-check**(阶段 1 并行):cargo deny(advisory/license/ban/source;独立 cargo-audit job 已删除——cargo-deny 已覆盖漏洞检查,避免维护两份忽略列表。`cargo audit` 仍作为本地 precheck 步骤,见下方检查清单)
4. **doc-check**(阶段 1 并行):cargo doc 零警告
5. **version-consistency**(阶段 2):Cargo.toml == CHANGELOG == tag,提取 CHANGELOG body
6. **publish-crates-io**(阶段 3):`cargo publish` 发布到 crates.io
7. **github-release**(阶段 4):从 CHANGELOG 提取 body 创建 GitHub Release(依赖 crates.io 成功,避免半发布)
8. **verify-release**(阶段 5):验证 GitHub Release + crates.io 索引传播
阶段 3 失败则阶段 4 不执行(避免 GitHub Release 已创建但 crates.io 未发布的半发布状态)。`concurrency` 控制块防止并发发布。
### 7. 验证发布
verify-release job 自动执行双重验证:
- GitHub Release:`gh release view v{version}`
- crates.io:`curl https://crates.io/api/v1/crates/garrison`(重试 6 次共 60 秒等待索引传播)
也可手动验证:
```bash
gh release view v0.7.1
cargo search garrison
```
### 8. 完成
- 通知用户/团队
- 如发布后需修正,参考下方"回滚"章节
## 回滚
如果发布后发现严重问题:
1. **crates.io 无法撤回已发布版本**,只能 yank(`cargo yank --vers 0.7.1`)
2. **删除 GitHub Release**:`gh release delete v0.7.1`
3. **删除 tag**:`git tag -d v0.7.1 && git push origin :refs/tags/v0.7.1`
4. **发布修复版本**:bump 到 0.7.2,重新走完整流程
## 紧急修复(patch release)
紧急修复流程:
1. 从最新 tag 创建 hotfix 分支:`git checkout -b hotfix/0.7.2 v0.7.1`
2. 修复 bug + 更新 CHANGELOG
3. 运行 `./scripts/release.sh precheck`
4. 提交 + 打 tag `v0.7.2`
5. 合并 hotfix 分支回 main:`git checkout main && git merge hotfix/0.7.2`
## 规则依据
- **规则 12**:失败必须显性化(不用 `continue-on-error`,cargo-audit/deny 未安装时 fail 而非 warn)
- **规则 18**:禁止 `--no-verify` 跳过 pre-commit / 安全审查
- **规则 19**:发布前强制 tiangang SAST + diting 代码审查(本地预检查等价)
- **规则 21**:文档与代码同步(CHANGELOG + 版本一致性检查)
- **规则 26**:commit 前并行派遣 3 个 subagent(安全/架构/性能)审查
- **project_memory**:cargo doc 零警告、所有测试通过、CHANGELOG 更新