版本管理#

FlagGems 使用 setuptools-scm 从 git 标签自动生成符合 PEP 440 规范的版本号。

版本格式#

源码中不硬编码任何版本号。 版本号完全在构建时从 git 标签派生。

+g<hash> 后缀（本地版本标签）会包含在本地安装和可编辑安装中， 开发者可以通过 git checkout <hash> 定位到对应的提交进行调试。 发布到 PyPI 时，该后缀会被自动去除。

标签命名规则#

开发周期#

每次稳定版发布后，创建一个开发标签来标记下一个版本周期的开始。 dev 标签不能和发布标签打在同一个 commit 上，否则后续补丁发布时需要 git tag -f 移动 dev 标签，容易遗漏。

做法：发布标签推送后，立即用一个空提交作为下一开发周期的起点，再把 dev 标签打上去：

# 发布标签已经推送（v5.4.0），继续执行：
git commit --allow-empty -m "Start v5.5.0 development cycle"
git tag v5.5.0.dev0
git push origin master v5.5.0.dev0

v5.4.0              ← 稳定版发布
  │
  │  Start v5.5.0 development cycle   ← 空提交
  │  v5.5.0.dev0                      ← dev 标签打在此处
  │
  ├── commit 1  ← 5.5.0.dev1+gabcdef0
  ├── commit 2  ← 5.5.0.dev2+g1234567
  ├── ...
  ├── commit N
  │
v5.5.0              ← 下一个稳定版发布

发布流程#

发布新版本（例如 v5.4.0）#

1. 确保该版本的所有 PR 已合并到 master 分支。

2. 打标签：

   git checkout master
   git pull origin master
   git tag v5.4.0
   git push origin v5.4.0

3. CI 自动构建发布产物。 release.yaml 工作流会在推送稳定版标签 （v<major>.<minor>.<patch>）时触发，自动构建 wheel 并发布到 PyPI。

4. 启动下一个开发周期：

   git commit --allow-empty -m "Start v5.5.0 development cycle"
   git tag v5.5.0.dev0
   git push origin master v5.5.0.dev0

   此后 master 上的所有提交将生成 5.5.0.dev1+gabcdef0 格式的版本号。

发布补丁版本（例如 v5.4.1）#

1. 如需要，创建发布分支：

   git checkout -b release/5.4 v5.4.0

2. Cherry-pick 或合并修复。
3. 打标签并推送：

   git tag v5.4.1
   git push origin v5.4.1

候选版本#

使用 v5.4.0rc1、v5.4.0rc2 等格式打标签。这些属于 PEP 440 预发布版本，不会触发发布工作流（仅匹配稳定版标签）。如需构建候选版本的 wheel，可手动触发工作流或临时调整标签过滤规则。

查看当前版本#

# 从 git 检出目录查看（诊断用途，安装时不需要）：
python -m setuptools_scm

# 从已安装的包查看：
python -c "import flag_gems; print(flag_gems.__version__)"