发布工作流

make release 完全指南:安全检查、版本推断与交互式预览

快速开始

❯ make release # 交互式发布(推荐) ❯ make release-quick # 自动化模式(保留 dry-run) ❯ make release-rehearse # 只排练完整检查,不修改仓库

发布流程

1

Pre-flight 检查

  • ✓ 验证在 dev 或 main 分支;从 main 启动时自动切换到 dev
  • ✓ 检查工作目录干净
  • ✓ 运行所有测试 (make test)
  • ✓ 运行 clippy (make clippy)
  • ✓ 运行格式检查 (make fmt) 并确认当前提交的 CI 状态
2

版本推断

脚本自动分析自上次 tag 以来的提交:

提交类型 版本升级 示例
feat! 或 BREAKING CHANGE Major 1.0.0 → 2.0.0
feat Minor 0.7.0 → 0.8.0
fix/refactor/perf Patch 0.7.0 → 0.7.1
3

交互式预览

你将看到:

  • 当前版本和上次 tag
  • 推断的版本升级
  • 提交摘要(features、fixes 数量)
  • Changelog 预览
  • 覆盖版本的选项(major/minor/patch/custom)
4

Dry Run

执行前,你将看到将要发生的操作:

  • 版本升级
  • Changelog 生成
  • 创建 release 分支与 PR
  • 版本、兼容性矩阵与 Changelog 更新
  • CI 门禁、Tag 与 CD 产物验证
  • crates.io 与 Homebrew 发布
5

Release PR 与 CI

确认后,脚本先:

  1. 从 dev 创建 release/vX.Y.Z 分支
  2. 升级 workspace 版本并更新兼容性矩阵
  3. 生成、验证并提交 CHANGELOG.md
  4. 创建指向 main 的 PR,等待所有 CI 通过后 squash merge
6

Tag 与 CD 验证

合并后创建 vX.Y.Z tag。CD 会构建多平台安装包、生成 SBOM、签名产物、创建 GitHub Release 并更新 Homebrew。脚本会等待 CD 完成并检查 Release 确实含有可下载产物,不会把“只推送了 tag”当成发布成功。

7

crates.io 与分支回同步

CD 在配置 CARGO_REGISTRY_TOKEN 时按依赖顺序发布全部公开 crate;本地流程也会提供手动补发选项。最后将 main 合并回 dev 并推送,避免两条长期分支漂移。

发布到 crates.io

前置条件

  1. Crates.io 账号:
    • 在 https://crates.io 注册
    • 验证邮箱
  2. GitHub Actions 认证(推荐):
    # Repository Settings → Secrets and variables → Actions CARGO_REGISTRY_TOKEN=<your-token>

    本地补发时可运行 cargo login,或仅在当前 shell 中设置 CARGO_REGISTRY_TOKEN。不要把 token 写入仓库文件。

  3. 验证 Crate 元数据:
    # 检查包是否就绪 ❯ cargo package --list ❯ cargo package --no-verify

发布选项

选项 A:CD 自动发布(推荐)

# 配置 CARGO_REGISTRY_TOKEN 后,推送 tag 即触发 ❯ make release

选项 B:本地补发

❯ make stage-skills-for-publish ❯ cargo release publish --execute --no-confirm \ --registry crates-io --allow-dirty ❯ make clean-staged-skills

选项 C:暂不发布

# 未配置 token 时 CD 会记录 warning 并跳过 # 可在后续重跑 workflow 或按选项 B 补发

注意事项

⚠️ crates.io 版本不可删除

一旦发布到 crates.io,版本无法删除或修改。只能 yank(隐藏),不能删除。必须发布新版本来修复问题。

ℹ️ 发布前检查清单

  • 所有测试通过
  • Clippy 无警告
  • 文档完整(cargo doc --no-deps)
  • CHANGELOG 已更新
  • README 中的版本号已更新(如需要)

已发布的 Crates

Crate 说明 链接
gitflow-cli 主 CLI 应用(二进制名 gf) crates.io →
gitflow-core 核心库 crates.io →
gitflow-cli-adapter-utils 平台 CLI 适配器共享工具 crates.io →
gitflow-github GitHub 平台支持 crates.io →
gitflow-gitlab GitLab 平台支持 crates.io →
gitflow-gitcode GitCode 平台支持 crates.io →
gitflow-jev Jev 类型化决策集成 crates.io →

准备好发布了吗?

运行 make release 开始你的第一次发布