Skip to content

RELEASE_PROCESS.md

Latest commit

 

History

History
261 lines (184 loc) · 7.33 KB

RELEASE_PROCESS.md

File metadata and controls

261 lines (184 loc) · 7.33 KB

Release Process（发布流程说明）

本仓库使用 GitHub Actions 完成构建、测试与发布。你会同时看到两类“产物”：

  • Actions Artifacts：每次 CI 运行都会上传到 workflow run 页面，适合临时下载验证。
  • GitHub Releases Assets：只在 master（Nightly）或 tag v*（正式版本）时发布，适合长期对外分发。

0. 名词速查

0.1 触发事件（Triggers）

  • Push / PR（任意分支）：构建 + 测试 + 上传 Actions artifacts（不发 Release）
  • Push 到 master：额外打包并发布 Nightly Release（固定 tag=nightly，资产会覆盖）
  • Push tag v*：发布 版本 Release（tag 就是版本号，资产默认不覆盖，永久保留）

0.2 两层“名字”（你现在的现状）

  1. Actions artifact 名（上传用）
    用于 workflow run 页面里下载，通常带矩阵信息避免冲突（409）。

  2. Release 资产文件名（包文件名）
    由 CPack（或你手工 zip）生成，上传到 Nightly/Release 里。

1. 一次完整 CI 会做什么

1.1 Push / Pull Request（日常）

目的： 确保编译 + 测试过关，并提供可下载的中间产物。

你在 GitHub 的某个 workflow run 中会看到：

  • matrix 全部条目构建（Windows/Linux/macOS，Debug/Release，gcc/clang/cl 等）
  • 运行测试（ctest）
  • 上传 artifacts（每个矩阵一份）

这里不会产生 Release。

1.2 Push 到 master（Nightly）

目的： 让仓库永远有一个“最新可用”的安装包下载入口。

CI 会额外做：

  • 打包（CPack 或脚本）
  • 将 tag nightly 移动到最新 master commit
  • 创建或更新 “Nightly” release
  • 上传资产时 覆盖同名资产（Nightly 允许覆盖，否则你会堆很多重复包）

✅ Nightly 的核心特征：同一个 Release，不断被更新。

1.3 Push tag v*（正式版本 Release）

目的： 发布一个“可追溯、不可变”的版本包。

CI 会做：

  • 打包
  • 创建该 tag 对应的 release（如 v0.1.0）
  • 上传资产时 跳过同名文件（默认不覆盖，保留永久资产）

✅ 正式 Release 的核心特征：同一个 tag 不建议反复移动（否则用户下载到的东西会不一致）。

2. 版本号规则（Versioning Rules）

2.1 基础版本（Base Version）

  • 基础版本在 CMakeLists.txt 里定义（例如 GRID_SIM_BASE_VERSION）。
  • 建议： 你每次要发正式 tag 前，先把 base version 改到目标版本，并提交到 master。

2.2 非 tag 构建版本（Nightly/PR）

  • 非 tag 构建建议显示成：<base>+g<shortsha>
    例：0.1.0+g73de572

2.3 tag 构建版本（正式 Release）

  • tag 构建版本建议用 tag 本身（去掉前缀 v）：
    例：tag v0.1.0 → 包版本 0.1.0

如果你还想“把 commit 号一起加上来”但又不想污染正式版本号，推荐做法是：
正式包文件名保持 0.1.0，但在包内写入一个 VERSION.txt / BUILD_INFO.txt（含 commit、构建时间、工作流号），可追溯且不破坏 semver。

3. 包文件命名建议（统一且可读）

3.1 二进制包文件名（Release/Nightly 资产）

推荐格式（字段顺序固定，便于排序/比对）：

GridSimSubsystem-<version>-<system>-<compiler>-<config>.(zip|tar.gz)

示例：

  • GridSimSubsystem-0.1.0+g73de572-Windows-cl-Release.zip
  • GridSimSubsystem-0.1.0-Linux-gcc-Debug.tar.gz
  • GridSimSubsystem-0.1.0+g73de572-Darwin-clang-Release.tar.gz

说明：

  • <system> 典型是 Windows / Linux / Darwin（来自 CMAKE_SYSTEM_NAME）
  • <compiler> 典型是 cl / gcc / clang
  • <config> 典型是 Debug / Release

3.2 源码包文件名（Source package）

你当前的原则是：源码包永远带 +g<hash>（与 tag 无关）。
建议格式：

GridSimSubsystem-<base>+g<shortsha>-Source.tar.gz

4. 你在 Git 里怎么“操作发布”

4.1 日常（Push/PR，只构建不发布）

你只需要正常提交并推送即可：

git add .
git commit -m "feat: something"
git push origin <branch>

PR 合并前后都只会有 workflow artifacts，不会产生 Releases。

4.2 Nightly（Push 到 master）

Nightly 不需要你手动打 tag；你只要 push 到 master：

git checkout master
git pull
# 修改代码...
git add .
git commit -m "fix: something"
git push origin master

CI 会自动：

  • 更新 nightly tag
  • 更新 Nightly release
  • 覆盖同名资产

4.3 正式 Release（打 tag v*）

推荐流程（例：发 v0.1.1）：

  1. 先改 base version 并提交到 master
git checkout master
git pull

# 修改 CMakeLists.txt: GRID_SIM_BASE_VERSION -> 0.1.1
git add CMakeLists.txt
git commit -m "chore: bump version to 0.1.1"
git push origin master
  1. 打 tag 并推送 tag
git tag -a v0.1.1 -m "v0.1.1"
git push origin v0.1.1

CI 会自动创建 v0.1.1 release 并上传资产（不覆盖已有同名资产）。

5. 常见问题与排错

5.1 gh release ... fatal: not a git repository

原因：release job 没有 actions/checkout，gh 默认尝试从 .git 推断仓库信息。
解决：在 release job 里显式指定仓库（你现在的做法）：

env:
  GH_REPO: ${{ github.repository }}

这样即使不 checkout，也能让 gh release ... 知道往哪个仓库发。

5.2 Windows CI / glad 需要 Python 依赖（如 jinja2）

如果 CI 里 glad 生成步骤报缺模块（例如 No module named 'jinja2'），常见处理方案：

  • 在 workflow 中显式安装 python 依赖（pip install jinja2 等）
  • 或改成使用预生成 glad 源码（把生成结果纳入仓库/Release 工件里），避免 CI 依赖网络与 Python 包

6. “重新发布”与“更正发布”的建议（重要）

6.1 Nightly：允许覆盖（推荐）

Nightly 的 tag 本来就是“移动的”，覆盖资产合理。

6.2 正式 tag：尽量不要移动（强烈建议）

如果你需要修正已发布版本，推荐这些做法之一：

  • 发新版本号（最干净）：v0.1.1 → v0.1.2
  • 加修订后缀：v0.1.1-1（也可以，但语义上不如直接 bump patch）

不推荐做法：

  • 删除并重打同名 tag（用户本地/缓存/镜像会非常混乱）

7. 我应该去哪里下载什么？

  • Actions artifacts：
    GitHub → Actions → 选中一次 run → Artifacts（临时产物）

  • Nightly 包：
    GitHub → Releases → Nightly（固定入口，永远是最新 master）

  • 正式版本包：
    GitHub → Releases → vX.Y.Z（永久保留）

8. 附录：几个常用 Git 命令（防手滑）

8.1 撤销一次 git add（保留文件修改）

  • 撤销全部暂存：
git restore --staged .
  • 撤销某个文件暂存：
git restore --staged .github/workflows/cmake-multi-platform.yml

8.2 撤销一次 commit（你还没 push 的情况）

  • 保留改动，只撤回 commit：
git reset --soft HEAD~1
  • 彻底丢弃改动（慎用）：
git reset --hard HEAD~1

8.3 tag 相关

  • 查看 tag：
git tag
  • 删除本地 tag：
git tag -d v0.1.0
  • 删除远端 tag：
git push --delete origin v0.1.0