TigerBeetle 发布流程全解析从 Release Manager 算法到二进制制品上线的工程实践【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetleTigerBeetle 以每周为默认节奏发布二进制版本其发布过程由一套被刻意过程化的 Release Manager 算法驱动周五准备变更日志并推送release分支周末由 CFO故障注入模拟器持续 fuzz 该分支周一触发 GitHub Actions 发布工作流并同步到各语言包管理器。本文以 docs/internals/releases.md 为主线结合 src/scripts/release.zig、src/scripts/changelog.zig 与 CHANGELOG.md 的实际实现完整还原 TigerBeetle 一次发布的幕后机制——包括版本号如何从 CHANGELOG 中推导、发布为什么幂等可重跑、热修复如何绕过 VSR 升级协议以及多版本multiversion二进制如何支撑无缝升级。读完本文你将能独立理解并执行 TigerBeetle 的发布全流程也能将其中的变更日志驱动版本 幂等发布 可跳过发布等工程思路迁移到自己的项目。注意原文档作者声明该流程仍在建立之中being established文档可能与现实并不完全一致且 TigerBeetle 发布流程面向仓库维护者maintainer需要 GitHub Actions、各包管理器密钥与仓库权限普通使用者只需关注如何消费制品无需执行本文中的操作。一次发布是什么TigerBeetle 为什么只发二进制TigerBeetle 以二进制形式分发而不是源码包。原文档给出了两个核心原因正确性真实机器码必须经过实际测试才能排除大量配置错误类别configuration errors——例如某些只在特定优化等级、特定目标平台上才暴露的问题语言稳定性Zig 语言本身尚未稳定not stable yet。以二进制发布可以把语言尚不稳定这一实现细节与用户隔离Zig 只是实现手段implementation detail用户无需关心。同时TigerBeetle 二进制与各客户端库同版本lockstep发布。这是因为当前客户端库的实现与 TigerBeetle 主程序紧密集成、共享代码要求服务端与客户端版本严格匹配。这一点在 src/scripts/release.zig 的VersionInfo结构中有直接体现第 54-66 行每个版本同时携带release_tripleVSR 升级协议使用的版本三元组major.minor.patch是协议视角的版本release_triple_client_minrelease_client_min配置项表示客户端最低兼容版本taggit tag 与客户端库版本号是符号视角的版本。正常情况下tag与release_triple完全一致热修复hot-fix时两者才可能不同。版本发布时还会在publish阶段src/scripts/release.zig生成 Release Notes其中明确写出Oldest supported client version最老受支持客户端版本即release_client_minOldest upgradable replica version最老可在线升级的副本版本从多版本二进制的头部解析而来。并附带重要提示不能用更新的客户端连接更老的集群——客户端只能兼容自己发布版本或更新的副本且受新版本Oldest supported client version约束。这一提示同时写入各客户端发布说明用于约束用户混用版本的边界。Release Manager 算法周五与周一原文档为发布经理release manager提供了一份简明算法succinct algorithm完整的动机解释在其后。整个算法按一周为周期运行默认在周一手动触发发布。周五准备发布打开 devhub 检查状态确认自己是本周的 release manager、VOPRViewstamped Replication 确定性模拟器结果正常近期提交无失败且成功运行充足、各项图表正常例如过去一周 RSS、数据文件大小、可执行文件大小没有剧烈变化。devhub 是发布轮换rotation与模拟器状态的集中入口也托管发布轮换表见下文发布物流一节。生成变更日志脚手架$ ./zig/zig build scripts -- changelog该命令会将本地仓库同步到远端git fetch origin --quiet、基于origin/main创建用于 changelog PR 的分支、并在 CHANGELOG.md 顶部追加一份新版本的脚手架。脚手架中的版本号会把 patch 版本自动 1## TigerBeetle 0.16.3 - Double check this version. Released 2024-08-29 - [#2256](https://github.com/tigerbeetle/tigerbeetle/pull/2256) Build: Check zig version - [#2248](https://github.com/tigerbeetle/tigerbeetle/pull/2248) vopr: heal *both* wal header sectors before replica startup ### Safety And Performance - ### Features - ### Internals - ### TigerTracks - []()这一脚手架实际上由 src/scripts/changelog.zig 程序化生成而不是手写。其核心逻辑format_changelog第 50-119 行运行git log --merges --first-parent origin/release..origin/main拉取自上次发布以来所有合入 main 的 merge 提交解析每个 merge 提交的 PR 编号与标题Merge pull request #NNNN from ...第 121-151 行若当天日期已出现在现有 changelog 中直接报错ChangelogAlreadyUpdated避免重复执行解析当前最新条目通过ChangelogIterator若其是版本化条目则生成patch 1的新版本号并打印## TigerBeetle {next}若当前条目是(unreleased)则沿用## TigerBeetle (unreleased)头第 71-80 行自动列出至多 128 个 PR超过会panic(suspiciously many PRs merged)追加固定的四个分区骨架### Safety And Performance、### Features、### Internals、### TigerTracks 。因此脚手架生成的## TigerBeetle 0.16.3只是自动推测的版本号发布经理必须人工 double-check。如果本周要跳过发布则把标题替换为## TigerBeetle (unreleased)。填写 changelog将 PR 归类到三个桶Safety And Performance / Features / Internals丢弃次要minorPR把相关的 PR 合并为一条要点再次核对版本号如果本次发布包含重大功能要在开头段落lead paragraph中说明对于安全/性能类变更要从用户视角表述其影响最后——挑选本周的 TigerTrack 曲目发布说明的惯例彩蛋。提交 changelog 并提 PR 供评审。PR 合并后推送release分支$ git fetch origin git push origin origin/main:release在 Slack 中发布发布 changelog 的可转推tweet-able摘要以及发布插画release sketch的点子。此后 CFO 将在周末持续 fuzzrelease分支。CFOChief Fuzz Officer即 VOPR 模拟器是 TigerBeetle 的确定性故障注入模拟器周末覆盖测试用于在发布前暴露潜在故障。在 Slack 中 下周的 release manager。周一正式发布由另一位不同release manager检查release分支上无 VOPR 失败。triage devhub 上未处理的问题能立即处理的立即处理无法行动的unactionable关闭并附评论或打上triaged标签否则转给能处理的人。触发发布工作流通过 GitHub Web 界面触发release.yml工作流务必从release分支触发否则会因权限问题失败。请另一个人批准该 GitHub 工作流人为的四人眼评审。将新的发布插画添加到对应的 GitHub Release 页面。发布物流与轮换发布是手动触发的默认在周一。默认的发布轮换表rotation托管在 devhub中间名middle name是本周的默认 release manager应当在周一执行 Release Manager 算法如果周一本人不在由志愿者顶替该次发布。跳过发布被刻意设计为便宜的选项由于发布频率高跳过单次发布完全不是问题。事实上让发布容易被跳过正是这套流程的明确目的之一如果某个 PR 让人觉得必须赶进下一个版本默认做法是让 PR 按自然节奏落地然后跳过这次发布如果纠结该发布还是跳过默认答案是跳过——跳过是廉价的Skipping is cheap!。跳过发布时changelog 仍然要在周一写好并合入但使用## TigerBeetle (unreleased)作为标题。下一个版本发布时需要手动设置下一个有效版本号把所有此前未发布的变更合并成一条带版本号的 changelog 条目以便升级用户了解增量信息。从源码看unreleased状态被ChangelogIterator显式建模src/scripts/changelog.zig 中当首行等于## TigerBeetle (unreleased)时release为nullsrc/scripts/release.zig 在解析版本时也会跳过release null的条目从而把此前 unreleased 的变更自然并入下一个版本号。错误处理幂等、fix-forward 与热修复原文档把发布异常分为三种场景分别给出处置策略1. 发布失败流程对客户端包是幂等的发布流程对客户端包是幂等的idempotent发布脚本会先检查每个包版本是否已发布已发布则跳过对应 src/scripts/release.zig 的is_already_published它对每个语言包的release_published_latest返回值与当前 tag 比对命中则直接return true。因此无论发布是完全失败还是部分失败例如 Node.js 包已上传但 Java 包失败都可以安全地重跑发布工作流修复底层问题 → 删除 draft release → 重新触发工作流。不会烧掉任何版本号No version number will be burned。这一幂等机制在 CHANGELOG.md 的 0.17.9 条目中有记录PR #3682 Make publishing TigerBeetle client artifacts idempotent是近期引入的发布健壮性改进。2. 发布成功但发现 bug走正常的 fix-forward如果发布已经成功但随后在代码中发现问题需要快速修复首选方式是做一次正常的 fix-forward 发布即在下一次正常发布中携带修复。虽然默认每周发布一次但一天内做多次发布也是可行的。需要注意fix-forward 发布会走正常的 VSR 升级协议即集群通过多版本二进制在线滚动升级。3. 发布很糟且正常升级协议失效同三元组热修复如果发布本身有问题且正常升级协议无法工作例如副本启动即崩溃可以制作一个使用相同 VSR release triple的发布从协议视角它被视为同一个版本。这种情况下git tag 与二进制内的 VSR release 会不一致。要制作这种发布需要手动调整release.zig中的version_info.release_triple。源码印证src/scripts/release.zig 中默认assert(std.mem.eql(u8, version_info.release_triple, version_info.tag))注释明确写道热修复发布时 tag 可以不同手动设置 tag 并移除该 assert若两者不同会打印log.warn(tag ! release, tag{s})。同时 src/multiversion.zig 的多版本机制允许二进制内含多个旧版本代码releases_bundled正是 VSR 升级协议能在运行时切换代码版本的基础。验证错误处理如果验证失败的原因是验证代码自身有 bug例如客户端的validate_release只需在main分支上修复即可release_validate.yml工作流会针对最新已发布 tag 的检出从main运行验证逻辑因此验证代码的修复会在下次验证运行时自动生效。版本管理CHANGELOG 是唯一事实来源因为发布频繁TigerBeetle刻意不在源码中硬编码版本号。版本号的唯一事实来源source of truth是 CHANGELOG.md顶部条目的版本号就是下一个新发布的版本号。版本号是单调递增的但允许存在缺口gaps——这正是跳过发布机制的直接后果跳过的版本不会出现在 CHANGELOG 中因此版本序列会出现 0.17.9 → 0.17.11 这类跳号。从 src/scripts/changelog.zig 与 src/scripts/release.zig 的交互可以看到版本推导的完整链路changelog 脚手架从最新条目推导patch 1src/scripts/release.zig 解析 CHANGELOG 顶部条目得到release当前版本与release_multiversion上一个已发布版本用于告诉多版本二进制要内嵌哪些旧代码并断言当前版本一定大于上一个多版本发布版本assert(release.value ...)且必须大于引导版本0.15.4见第 122-127 行src/config.zig 在编译期通过 build options 接收-Dconfig-release与-Dconfig-release-client-min解析为vsr.Release并断言release release_client_min。这也解释了为什么./zig/zig build scripts -- changelog生成的脚手架头部要特别标注Double check this version——版本号来自对 CHANGELOG 的机械推导人工必须复核。Changelog 的编写原则原文档明确了 changelog 的三个用途对所有人给项目一个可见的脉搏pulse对 TigerBeetle 开发者讲述细粒度的项目演进故事形成共享上下文为月度 newsletter 提供素材对 TigerBeetle 用户告知所有可见的、可能相关的变化。据此编写时有四条指导原则平凡的变更trivial changes考虑跳过有意义的内部变更internals即使外部不可见也不能跳过如果一系列 PR 背后有故事把它讲出来tell the story别忘了本周的TigerTrack实际条目格式可参考仓库根目录 CHANGELOG.md 的 0.17.9 条目每个分区下列出 PR 编号链接与一至两句描述多个相关 PR 合并为一个要点如 Add a u128 bounds check in the Ruby client and make its status return type more idiomatic 合并了 #3830 与 #3811。发布制品与发布Publishing一次发布的规范形态dist/目录一次发布的规范形态canonical form是一个dist/文件夹包含以下制品子目录内容目标注册中心tigerbeetle/所有受支持架构的tigerbeetle二进制.zipGitHub Release Dockerghcr.iodotnet/NuGet 包NuGetgo/go 客户端源码 各平台预编译原生库独立的 tigerbeetle-go 仓库通过提交java/.jar文件Maven Centralnode/npm 用的.tgz包npm从 src/scripts/release.zig 可以看到 TigerBeetle 二进制实际构建的目标矩阵x86_64-linuxx86_64-windowsaarch64-linuxaarch64-macos会构建成 universal binary每个目标还会额外构建debug 变体-debug对应build.modeDebug供排查问题使用并打 zip 包tigerbeetle-{target}.zip与tigerbeetle-{target}-debug.zip。构建完成后会在本机目标上运行./tigerbeetle version --verbose断言process.verifytruedebug与正确的构建模式第 304-318 行确保制品自检通过。发布脚本同时会为每个客户端语言执行各自的构建.dotnet、.go、.java、.node、.python、.ruby、.rust——rust 当前处于禁用状态见第 241-244 行注释 Currently disabled并把产物写入zig-out/dist下对应的子目录。此外还会额外构建 Vortex 驱动器vortex-driver-zig-{target}.zip第 333-368 行供故障注入测试使用。发布Publishing流程发布的同步机制如下发布开始时先创建一个draft releasegh release create --draftsrc/scripts/release.zig且发布前会做 sanity check新 tag 必须尚不存在而 multiversion 参考 tag 必须已存在第 692-711 行制品依次上传到GitHub Release二进制 zip 与 vortex 包第 808-823 行、npm、Maven Central、NuGetGo 客户端以新 commit 推到独立的 tigerbeetle-go 仓库并打上v{tag}与tigerbeetle-{sha}两个 tag第 870-926 行文档则上传到独立的 docs 仓库publish_docs第 1223-1279 行即使文档无变化也会提交一个--allow-emptycommit确保 docs 仓库的最新 commit 总是指向最新发布只有所有注册中心都发布成功发布才会从 draft 转为正式gh release edit --draftfalse --latesttrue第 836-840 行文档发布放在最后即使失败也不影响其余制品。发布还包含 Docker 镜像publish_docker第 1126-1208 行用docker buildx build构建linux/amd64,linux/arm64多架构镜像并 push 到 ghcr.iolatest与{tag}、{tag}-debug共三个 tag发布后还会docker run ... version --verbose做事后验证。注意源码注释特别说明Docker 不是运行 TigerBeetle 的推荐方式容器镜像只是为期望它的用户提供的便利第 1124-1125 行。密钥管理所有发布密钥都以GitHub Actions secrets的形式存储在release环境中。其中 Go 与 docs 使用个人访问令牌PAT这类令牌一年后过期。刷新步骤用个人 GitHub 账号创建 fine-grained PAT将令牌作用域限定到 tigerbeetle GitHub 组织授予相关仓库的写权限不同仓库使用不同令牌在 tigerbeetle 仓库的release环境中更新令牌。Ruby 客户端则使用OIDC trusted publishingsrc/scripts/release.zig从 GitHub Actions 获取 OIDC token与 rubygems.org 交换 API key免去长期密钥管理。深入源码release.zig 如何编排这场元构建src/scripts/release.zig 被刻意实现为独立的 Zig 脚本而不是build.zig中的一个步骤。文件头注释第 1-16 行说明了原因这是一个元构建系统meta build system需要把zig build、go build、npm publish等对等的工具编排在一起。它支持通过 CLI 参数精细控制--sha发布所基于的 commit SHA--languages只构建/发布特定语言Language枚举dotnet、go、java、node、python、ruby、rust、zig、docker第 38 行--build/--publish区分构建与发布两个阶段--no-changelog当当前代码没有 changelog 条目时使用即顶部条目描述的是历史发布用于在 main 分支上测试发布流程第 45-49 行此时会以65535.0.0作为假版本且禁止 publish--devhub只构建生产用 x86_64 Linux 目标加快 devhub 触发的构建速度仅允许与--languageszig组合第 76-80 行。发布过程中的出错体验也被刻意优化每个命令的输出保持 O(1) 行这样一旦出错能立刻看到是哪条命令出了问题并可直接复制粘贴到本地终端复现第 13-16 行。另外值得注意的是构建过程会对每个语言修改其版本文件如 Java 的pom.xml、Node 的package.json/package-lock.json、Ruby 的version.rb、Rust 的Cargo.toml但都通过backup_create/backup_restore第 1293-1301 行在构建前后备份恢复保证主仓库不被污染。相关文档docs/internals/README.mdTigerBeetle 内部文档索引其中将本文件描述为我们的发布流程docs/internals/upgrades.mdVSR 升级协议fix-forward 发布与热修复背后的协议基础docs/internals/vopr.md 与 docs/internals/testing.md周末 fuzz 的 CFO/VOPR 模拟器说明CHANGELOG.md版本号的唯一事实来源也是发布脚手架的输入与输出src/scripts/release.zig发布编排脚本构建 发布src/scripts/changelog.zigchangelog 脚手架生成器src/multiversion.zig多版本二进制实现支撑运行时无缝升级。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考