Prometheus 发布流程全解：从版本排期、分支管理到打 Tag 发布的执行手册

本文基于 Prometheus 仓库中的 RELEASE.md 编写，完整梳理官方发布流程的两大主题：v3 系列的发布排期与"发布牧人（Release Shepherd）"制度，以及单个版本从依赖更新、版本号提升、CHANGELOG 整理到打 Tag、发布库版本、跑基准测试的完整操作链路。读完后，你将能够理解 release-x.y 分支的维护策略、VERSION 文件与 UI 模块版本的联动关系，并掌握 scripts/generate_release_notes.sh、make ui-bump-version、scripts/get_module_version.sh 等官方工具在发布中的具体用法。

发布排期与 Release Shepherd 制度

Prometheus 采用"固定节奏 + 自愿认领"的发布组织方式：首个预发布（pre-release）的切出节奏为 6 周一个 minor 版本，每个 minor 版本由一位自愿认领的发布牧人（release shepherd）负责该 minor 的全部预发布与补丁版本。

当前 RELEASE.md 中登记的排期表如下：

发布系列	首个预发布日期（年-月-日）	发布牧人
v3.0	2024-11-14	Jan Fajerski（@jan--f）
v3.1	2024-12-17	Bryan Boreham（@bboreham）
v3.2	2025-01-28	Jan Fajerski（@jan--f）
v3.3	2025-03-11	Ayoub Mrini（@machine424）
v3.4	2025-04-29	Jan-Otto Kröpke（@jkroepke）
v3.5 LTS	2025-06-03	Bryan Boreham（@bboreham）
v3.6	2025-08-01	Ayoub Mrini（@machine424）
v3.7	2025-09-25	Arthur Sens 与 György Krajcsovits（@ArthurSens、@krajorama）
v3.8	2025-11-06	Jan Fajerski（@jan--f）
v3.9	2025-12-18	Bryan Boreham（@bboreham）
v3.10	2026-02-05	Ganesh Vernekar（@codesome）
v3.11	2026-03-25	Julien Pivotto（@roidelapluie）
v3.12	2026-05-06	Bartek Plotka（@bwplotka）
v3.13	2026-06-17	György Krajcsovits（@krajorama）
v3.14	2026-07-29	Ayoub Mrini（@machine424）
v3.15	2026-09-09	Jan Fajerski（@jan--f）
v3.16	2026-10-21	虚位以待，欢迎志愿者

从排期表可以看出两个细节：其一，v3.5 被标记为 LTS 系列，说明发布制度中预留了长期支持版本的定位；其二，当前仓库根目录的 VERSION 文件内容为 3.14.0，与排期表中 v3.14 的推进状态（首个预发布定于 2026-07-29）相吻合，且 CHANGELOG.md 中最新的稳定版本条目为 ## 3.14.0 / 2026-08-17，验证了排期表、版本号文件与变更日志三者在流程上是联动的。

对排期表中"volunteer welcome"的空缺，文档给出的参与方式是：通过向 Prometheus 仓库提交 pull request，在排期表中自荐成为所选 minor 系列的发布牧人。

发布牧人的四项核心职责

发布牧人负责一个 minor 版本从初始预发布到补丁版本的全部工作。流程正式始于首个预发布，但准备工作需提前数天展开。文档明确了四项职责：

1. 保持 main 分支随时可发布。目标是 main 分支在任何时刻都处于可用状态，原则上任何时候都能从 main 切出发布。实际操作中，牧人应在预发布日期前几天检查 main 的状态：依其判断，推动那些已在进行中、且理应赶上进本版本发布的 bug 修复尽快合入；同时可以暂缓合并那些最后时刻的、侵入性强且风险高的变更，把它们留给下一个 minor 版本。
2. 切出首个预发布（后缀 -rc.0）。在排期表所列日期，牧人切出第一个预发布，并以该预发布所打的 tag 对应的 commit 为起点创建 release-<major>.<minor> 分支。预发布即"release candidate（候选发布）"，因此原则上不应包含任何已知且计划在正式版本中修复的 bug。
3. 运行并监控 3 天基准测试。预发布切出后，牧人需负责运行并监控该预发布为期 3 天的基准跑测（benchmark），若结果成功，该预发布即可晋升（promote）为稳定版。
4. 处理回归与关键缺陷。一旦发现回归或严重 bug，必须先修复，再切出新的预发布（命名依次为 -rc.1、-rc.2 等）。

分支管理与版本化策略

官方发布流程声明采用语义化版本（Semantic Versioning），并且其分支策略是所有操作的结构性前提，值得单独展开：

• 每个 minor 版本维护一个独立分支，命名为 release-<major>.<minor>，例如 release-2.1、release-3.0。
• 分支保护规则：任何以 release- 开头的分支名会自动触发仓库的分支保护机制。因此，绝不要把非发布分支命名为 release- 开头，否则该分支会意外进入受保护状态。
• 常规合流路径：
  • 新特性与一般变更合入 main；
  • bug 修复先合入最新的 release 分支，再反向合回 main；
  • main 分支必须始终包含最新 release 分支的全部 commit；
  • 只要 main 尚未与 release 分支产生分叉，新 commit 也可以先提交到 main，再把 main 合回 release 分支。
• cherry-pick 补救路径：如果某次 bug 修复在 main 上已经混入了非 bug-fix 的变更之后才被合入 main，则这些 bug-fix commit 必须被 cherry-pick 到 release 分支，然后再合回 main。文档特别提示应尽量回避这种局面。
• 旧版本分支的维护是 best effort（尽力而为）：对较老 minor 版本的 release 分支维护采取尽力而为原则，不做硬性承诺。

此外文档还说明：同一 major/minor 下的 release candidate 与补丁发布都发生在同一个 release-<major>.<minor> 分支内，不要为补丁版本或 RC 另建 release-<version> 分支。

发布前置：依赖更新与实验特性晋级/降级

在 major 或 minor 版本发布前的数天，官方建议执行两类准备工作。

依赖更新

Prometheus 使用 Dependabot 持续自动更新大部分依赖，其配置见 scripts/dependabot.yml，因此多数依赖通常已是最新。牧人需要检查仓库中标记为 dependencies 的 PR 是否有未处理的更新。文档特别指出，该机器人目前不管理 Go 模块版本说明符中的 +incompatible 与 v0.0.0 这两类非语义化版本，这类情况需要手工处理：

make update-all-go-deps

依赖更新后需要警惕各类"怪异"现象，包括但不限于：flaky 测试、资源占用变化、panic 等。若有疑虑或问题不能在合理时间内解决，可以跳过依赖更新或仅更新部分依赖——但此时必须创建 issue 或 pull request 以便后续跟进。

关于 UI（React 应用）依赖，文档说明 UI 已迁移到包含多个内部 npm 包的 monorepo 体系，依赖升级目前相当敏感。查看仓库可印证这一结构：web/ui/package.json 是名为 prometheus-io 的工作区根包，其下还有 @prometheus-io/mantine-ui、@prometheus-io/app（位于 react-app 子目录）、@prometheus-io/codemirror-promql、@prometheus-io/lezer-promql 等多个内部包。升级 UI 依赖的命令为：

make update-npm-deps

对应 Makefile 中的定义，该目标实际调用 scripts/npm-deps.sh 脚本并传入 "minor" 参数，即只做 minor 级别的依赖提升。此步骤完成后需要验证各模块子目录没有产生额外的 node_modules 目录（那可能意味着跨模块的依赖版本冲突），再运行 make ui-build 确认构建仍正常。文档还提到：偶尔需要用 make upgrade-npm-deps（对应传入 "latest"）把 npm 依赖升级到最新 major/minor 版本，但这可以在与发布节奏解耦的便利时机由 UI 维护者执行，不必绑定每次发布。

实验特性的晋级与移除

依赖更新也是审视实验特性与 feature flag 的好时机：哪些应晋级为稳定（stable）、哪些应弃用（deprecate）或彻底移除。要求是每个特性一个独立的 pull request，逐一处理。文档还给出一个校验步骤：依赖更新后检查仓库的安全告警是否已全部关闭；若告警不严重（例如上游修复尚未发布、或与依赖升级无关、或确认不受影响），则可以暂不处理。

准备发布：VERSION、CHANGELOG 与 UI 版本联动

进入正式准备阶段（以发布 3.7.0 为例，上一稳定版为 3.6.0）：

1. 基于 main 分支创建对应的 release-3.7 分支（所有发布都在受保护的 release 分支上进行）。
2. RC 与补丁版本的变更，一律通过 pull request 合入对应的 release 分支。
3. 提升 VERSION 文件中的版本号并更新 CHANGELOG.md。这一步必须走一个指向 release 分支的正式 PR——因为要让其他维护者有机会对发布内容本身、特别是对 CHANGELOG 条目发表意见。若为 release candidate，版本号需追加类似 -rc.0 的后缀（tag 名、release 名等相应同步修改）。

用脚本生成 CHANGELOG 草稿

仓库提供 scripts/generate_release_notes.sh 来产出 CHANGELOG 条目的起点。它依赖 release-notes 工具与一个具备读权限的 GITHUB_TOKEN，运行方式为：

GITHUB_TOKEN=<token> scripts/generate_release_notes.sh 3.Y_SET_ME.Z_SET_ME

版本参数可以是 RC、正式版或补丁号，例如 3.11.0-rc.0、3.11.0、3.11.1。从脚本源码可以看清它区分了两类生成逻辑：

• minor 版本（patch 为 0，含其 RC 与正式版）：以 v<major>.<minor-1>.0-rc.0 tag 的父 commit 为起点、release-<major>.<minor> 分支为终点，覆盖上一个 minor 切分支以来的完整周期（见 scripts/generate_release_notes.sh#L54-L67）；
• 补丁版本：以上一个补丁 tag v<major>.<minor>.<patch-1> 为起点，并加 --skip-first-commit 跳过起点 commit 本身（见 scripts/generate_release_notes.sh#L68-L83）。

脚本内置的 Go 模板会按 [SECURITY]、[CHANGE]、[FEATURE]、[ENHANCEMENT]、[PERF]、[BUGFIX] 的优先级对 PR 标题前缀排序输出，最终形态如 CHANGELOG.md 中的 ## 3.14.0 / 2026-08-17 条目所示。文档要求仔细审阅输出后再写入 CHANGELOG.md，重点是两条筛选原则：

• 删除已出现在上一版本 changelog 中的条目——由于修复可能先合入上一 release 分支，重复条目很常见；
• CHANGELOG.md 只记录对用户有相关性的变更：外部 API 变化、性能改进、新特性。内部接口改动、代码重构与清理、构建流程变化等不应记录，对这类变更感兴趣的人应参考 git 历史。

提升 UI 模块版本

完成上述工作后，还需要提升 UI 模块的版本号：

make ui-bump-version

查看 Makefile 中该目标的定义可以还原其完整动作：先运行 scripts/get_module_version.sh 计算目标版本，再调用 scripts/ui_release.sh 的 --bump-version 子命令，随后在 web/ui 与 web/ui/react-app 两个工作区分别执行 pnpm install，并把 pnpm-lock.yaml 与所有 package.json 的变更一并 git add。

scripts/get_module_version.sh 的版本映射规则是理解 Prometheus "服务器版本 vs 库版本"双轨制的钥匙：对 major 为 2 的版本输出 0.<minor>.<patch>（如 v2.55.0 → 0.55.0）；对 major 为 3 的版本输出 0.3<两位minor>.<patch>（如 v3.14.0 → 0.314.0）。当前仓库中 web/ui/package.json 的 "version" 字段恰为 0.314.0，与 VERSION 中的 3.14.0 完全对应——这正是该脚本在上一轮发布中被执行过的直接证据。

以上所有变更（VERSION 提升、CHANGELOG 更新、UI 版本提升与锁文件变更）汇聚为一个指向 release-x.y 分支的 PR，等待 CI 通过并获得批准。PR 合入 release 分支并同步到本地工作区后，即可进入打 tag 环节。

打 Tag 发布服务器版本

服务器版本的发布通过以下命令完成：

tag="v$(< VERSION)"
git tag -s "${tag}" -m "${tag}"
git push origin "${tag}"

也可以配置一个便捷的 .gitconfig alias：

[alias]
  tag-release = "!f() { tag=v${1:-$(cat VERSION)} ; git tag -s ${tag} -m ${tag} && git push origin ${tag}; }; f"

然后执行 git tag-release 即可。用 GPG 密钥对 tag 签名是官方推荐做法；若无法把 GPG key 添加到 GitHub 账号，可将 git tag 的 -s 改为 -a，只做带注释的 tag 而不签名。

tag 推送后，GitHub Actions 会被该 tag 触发，自动用 prombot 账号起草（draft）GitHub Release。此后的关键动作是等待该 tag 的构建步骤完成——标志是 tarball 已上传到 GitHub Release、容器镜像已推送到 Docker Hub 和 Quay.io——之后再点击 Publish release，使发布对外可见并产生 GitHub 通知。文档特别提醒：对于 release candidate 版本，务必确认草稿界面中勾选了 This is a pre-release 选项；CI 应会处理这一点，但点发布前人工复查一次更稳妥。仓库中的 .github/workflows/check_release_notes.yml 与 .github/workflows/prombench.yml 等 workflow 文件，正是这套 tag 触发式自动化在仓库内的落点。

打 Tag 发布库（Go Module）版本

Go 模块的版本化要求严格使用语义化版本。由于 Prometheus 不承诺服务器 minor 版本之间库代码不出现破坏性变更，因此库采用**零主版本（major version zero）**策略：服务器发 v3.x.y 时，库对应发 v0.3xy.z。

给库打 tag 的操作与常规发布类似，但没有后续的构建与发布步骤：

tag="v$(./scripts/get_module_version.sh)"
git tag -s "${tag}" -m "${tag}"
git push origin "${tag}"

结合前文 scripts/get_module_version.sh 的解析逻辑，这条命令会把 VERSION 中的 3.14.0 换算成库 tag v0.314.0。这个"服务器 tag 与库 tag 分离打点"的设计，是 Prometheus 作为被大量第三方项目引用的 Go 库（如配置、模型、抓取等包）时保证依赖语义清晰的关键机制。

收尾工作：基准测试、合流与公告

发布并非在点下 Publish release 后结束，官方流程还有三个收尾动作：

1. 对 RC 版本跑 3 天基准测试。对 release candidate（如 v3.6.0-rc.0），使用 /prombench vX.Y.Z 命令触发基准跑测，其中 vX.Y.Z 取上一个 minor 系列中最新稳定补丁版本的 tag（例如上一系列为 3.5 时取 v3.5.2）。以稳定版为基线对比，正是前文"预发布需成功通过 3 天基准跑测后方可晋升为稳定版"这一牧人职责的具体执行手段。
2. 把 release 分支的变更合回 main。若发布发生在最新的 release 分支上，需将相关变更合并入 main，维持"main 始终包含最新 release 分支全部 commit"的不变式。
3. 发布公告并寻找下一任牧人。二进制上传完成后，在 [e-mail] 邮件列表发布公告（文档明确指出不要再使用 [e-mail] 做发布通知），可参考以往公告邮件的措辞。最后，若排期表中下一版本还没有 release shepherd，就要去找一位志愿者认领。

小结

Prometheus 的发布流程由"制度"与"操作"两层构成：制度层是 6 周节奏的 minor 排期表与发布牧人负责制（切 RC、盯 3 天基准、处理回归）；操作层则是从依赖更新（Dependabot + make update-all-go-deps / make update-npm-deps）、实验特性晋级，到 VERSION/CHANGELOG/UI 版本三处联动（scripts/generate_release_notes.sh、make ui-bump-version）、打服务器 tag 触发 GitHub Actions 自动起草发布、再打库 tag（scripts/get_module_version.sh 的版本映射）的完整链路。分支模型（main 与 release-x.y 的双向合流、cherry-pick 补救路径）是贯穿其中的骨架。对于维护者而言，RELEASE.md 与 Makefile、scripts 目录共同构成了一份可直接照做的发布操作手册；对于使用者而言，理解这套机制有助于解释版本号中 -rc.x 后缀的含义、UI npm 包 0.3xy.z 版本的由来，以及为何某些修复会先出现在补丁版本中。