TFRSManager 版本管理¶

统一版本与分支规则¶

产品版本唯一来源是 .bumpversion.toml 的 tool.bumpversion.current_version，由固定版本的 bump-my-version 1.5.1 管理。命名与 tfrs-operator 对齐：{major}.{minor}.{patch}-{pre_l}{pre_n}；正式版省略后缀。首个开发版本为 0.1.0-dev0。

对象	示例	规则
配置、二进制、OTEL 默认版本	`0.1.0-dev0`	相同的产品版本，不拼分支、提交数量或 SHA
Git tag	`v0.1.0-dev0`	仅 Git tag 加 `v`，指向合并后的准确源码提交
四个镜像 tag	`0.1.0-dev0`	user-service、admin-service、otlp-receiver、migrate 使用相同版本
GitCommit / OCI revision	完整 40 位 SHA	与版本分开记录；不同镜像有各自 digest
GitTreeState	`clean` / `dirty` / `unknown`	工作区状态单独记录，不改变产品版本
Atlas schema 版本	迁移时间戳	保持既有数据库契约，不随产品版本重置

分支	发布构建允许的版本
develop	仅 `x.y.z-devN`
main / master	`x.y.z-rcN`、`x.y.z-alphaN`、`x.y.z-betaN` 或正式版 `x.y.z`，禁止 dev
其他（含 deploy）	可本地编译和运行 PR 测试，不开放产品发布构建

通常采用 dev0 → dev1 → rc0 → rc1 → 正式版。不生成 dev.0、rc.0、develop-<sha> 或 git describe 格式的新发布版本。旧 v1.0.1-* Git tag 和已发布镜像保留，不改写历史；新版本线从 0.1.0 开始，因此数值低于历史版本，选取新制品须明确指定版本/SHA，不能按所有历史 tag 的最大值选择。

分支限制只在发布构建执行。普通 PR（包括 develop → main）只校验版本格式和回归脚本，不因 PR 携带 dev 版本被阻塞。main 合并 dev 后，必须先将版本切到 rc 或正式版才能发布。

开发与升级¶

安装 uv 后可直接使用 Makefile（uvx 调用固定版本工具）；也可安装 bump-my-version 1.5.1 并传入 BUMP_MY_VERSION=bump-my-version。

make version
make version-check
make version-bump-preview PART=pre_n
# 以下命令修改配置并创建本地 commit，需在干净的版本工作分支执行。
make version-bump PART=pre_n                       # dev0 → dev1，或 rc0 → rc1
make version-bump PART=pre_l TO=0.1.0-rc0           # 从开发阶段进入候选发布阶段
make version-bump PART=pre_l                       # rcN → 正式版
make version-bump PART=patch                      # 0.1.0 → 0.1.1-dev0
make version-bump PART=minor                      # 下一次版本，后缀重置 dev0
make version-bump PART=major                      # 下一主版本，后缀重置 dev0

pre_l 默认阶段顺序为 dev → alpha → beta → rc → final；跳过 alpha/beta 时显式使用 TO。预览使用 --dry-run --verbose，不修改文件或历史。bump 自动更新自身配置，不重复将 .bumpversion.toml 配置为待替换文件。

与 Operator 自动打 tag 的操作差异：本仓 tag=false，升级只创建本地 commit；合并版本 PR 后再打 tag，避免 squash/rebase 合并造成 tag 与最终源码 SHA 不一致。升级不会自动推送、构建或部署。

发布镜像（CNB）¶

将版本修改 PR 合入相应分支，取得并确认合并后的完整 SHA。
在干净的准确提交上创建注解 tag v<配置版本>，只推送该 tag；不推送全部历史 tag。
对该分支的同一 SHA 触发现有 web_trigger_build_*_image / api_trigger_build_*_image 或 *_build_all_images。镜像构建仍为 AMD64，tag push 不自动触发镜像构建。
流水线精确获取本版本 Git tag，检查分支规则、工作区干净、tag 对应 SHA 等于 HEAD。浅克隆不依赖历史 tag；detached HEAD 必须有可信的 CNB_BRANCH。缺失/不匹配直接失败。
IMAGE_TAG 默认留空；非空时必须等于配置版本，latest 或其他自定义名称会被拒绝。四个镜像注入相同版本/源码 SHA、各自构建时间，推送前检查 OCI 标签。
全部镜像成功后分别记录 digest；部分镜像成功不代表整组版本完成。GitOps 使用明确制品引用，继续遵守迁移/应用两阶段发布流程。

本地只读预检：

# 校验当前分支与版本，不要求 Git tag：
bash scripts/version.sh policy
# 校验发布条件，不进行任何网络请求或镜像构建：
make version-release-check BRANCH=develop

发布入口不会修改版本文件、自动打 tag、推送源码或部署集群。版本 tag 与源码 SHA 应保持不可变；需要改变源码时升级版本，不能移动旧 tag 复用产品版本。

构建信息¶

internal/shared/version/version.go 提供 Version、GitCommit、BuildTime、GitTreeState。Makefile 和 Dockerfile 通过 -ldflags -X 注入。三个服务启动日志输出这些字段，OTEL 保持原有 OTEL_SERVICE_VERSION 显式覆盖机制，默认使用产品版本。

本地 make build-all 自动读配置，不接受不同的 VERSION 覆盖；SHA 与 dirty 独立注入。直接 go run / go build 不经过注入入口时，保留 dev / unknown 开发默认值。直接调用 Dockerfile 时调用者负责提供 build args，生产发布必须经 CNB 校验入口。

四个镜像都有 org.opencontainers.image.version/revision/created 和原有 com.turingfocus.* 标签，并记录 com.turingfocus.git_tree_state。迁移镜像的产品版本只写标签，Atlas CLI 自身版本保持固定。

验证¶

make test-version
TEST_VERSION_BUILD=1 make test-version  # 编译运行微型 Go 模块，验证真实 Makefile 注入
make test-version-bump                  # 实际 bump 工具，验证阶段递进、commit、无 tag、dirty 拒绝

测试全部使用临时 Git 仓库，不改动项目历史。覆盖格式、分支矩阵、自定义镜像 tag、准确 Git tag/SHA、脏工作区、浅克隆和 detached HEAD。CI 同样运行这些测试；镜像构建和镜像标签验证只在流水线执行，本次不在本地构建镜像。

本变更没有数据库迁移、API、Seed 数据或必填运行环境变量变化，无 UAT/Seed 影响。GitOps 后续发布需要采用新的纯版本镜像名称；本仓修改不会自动改变现有部署。