OpenTelemetry Go 发版全流程解析从 semconv 生成到 Tag 签名与 Post-Release【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkitOpenTelemetry Gogo.opentelemetry.io/otel是一个多模块multi-moduleGo 仓库其发布流程远比普通 Go 项目复杂需要处理 Semantic Conventions 升级、多模块集版本同步、breaking change 校验、上游 tag 与 GPG 签名等环节。本文以仓库内vendor/go.opentelemetry.io/otel/RELEASING.md为骨架结合 Makefile、versions.yaml、CHANGELOG.md 等仓库内实现完整拆解一次 OTel Go 发布从创建 Issue 到关闭 Milestone 的每一步让读者能照此独立执行一次发版并理解每个 make target 背后的工作原理。该流程同样适用于 buildkit 这类深度依赖 OTel 的 Go 项目理解上游版本节奏与升级风险。一、发布前奏创建Version ReleaseIssue 与模块集规划发布流程的第一步是创建名为Version Release的 Issue用来跟踪整个发布过程的进度。由于 OTel Go 采用多模块仓库结构一次发布往往同时推进多个模块集module set因此在动手前必须明确本次要发布哪些模块集、各模块集的新版本号是多少。模块集的版本规划集中在 versions.yaml 中。以当前仓库内快照为例共分 4 个模块集stable-v1版本v1.45.0涵盖go.opentelemetry.io/otel主模块及 sdk、trace、metric、OTLP 各类 exporter 等 16 个稳定模块experimental-metrics版本v0.67.0包含 prometheus exporter 与metric/x实验 APIexperimental-logs版本v0.21.0包含log、sdk/log与 OTLP log exporterexperimental-schema版本v0.0.18对应schema模块。从该文件还可看到 OTel Go 的版本管理约束excluded-modules明确排除internal/tools与测试辅助模块避免它们被误发版modules段则为部分 exporter 声明version-refs指向各自的internal/version.go确保这些子模块的版本常量与发版 tag 保持一致。发布者需要先在versions.yaml中更新目标版本号并提交到新分支后续的 prerelease、add-tags 全部以这里的版本为准。二、Semantic Convention 升级生成新 semconv 包OpenTelemetry 的 Semantic Conventions语义约定由独立仓库维护每次约定仓库发新 tagOTel Go 就需要在semconv下生成对应的新版本子包。2.1 使用make semconv-generate生成代码在仓库根目录设置TAG环境变量指向要生成的语义约定 tag然后执行export TAGv1.30.0 # 改为你要生成的目标版本 make semconv-generate # 读取导出的 TAG 变量从 Makefile 可以看到该 target 的真实行为它首先校验TAG是否已设置未设置直接报错退出然后创建semconv/TAG目标目录并调用weaver镜像执行registry generate——weaver 从 OpenTelemetry semantic-conventions 仓库的 tag 归档拉取模型套用semconv/templates目录下的 Go 模板渲染出代码最后再由semconvkit工具补全包元信息。整个过程通过 Docker 完成因此执行机器需要能访问 Docker 以及 OpenTelemetry 语义约定仓库的归档地址。生成完成后semconv目录下会出现一个新的版本子包。以当前仓库为例semconv 下共存v1.21.0、v1.37.0、v1.43.0三个版本新版本包应与它们保持同样的目录结构attribute_group.go、resource.go、trace.go等。提交 PR 前应检查生成结果是否合理。2.2 更新 CHANGELOG新 semconv 包必须登记到 CHANGELOG.md格式如下注意NEW VERSION、PREVIOUS VERSION、PR 编号需替换为真实值- The go.opentelemetry.io/otel/semconv/NEW VERSION package. The package contains semantic conventions from the NEW VERSION version of the OpenTelemetry Semantic Conventions. See the [migration documentation](https://link.gitcode.com/i/240ccfc9eabe7de2e3d0d784eaee5346) for information on how to upgrade from go.opentelemetry.io/otel/semconv/PREVIOUS VERSION. (#PR_NUMBER)仓库中的真实案例即此格式CHANGELOG 中记录了新增v1.42.0、v1.43.0包的条目并各自附上指向./semconv/v1.43.0/MIGRATION.md的迁移文档链接。迁移文档由生成器产出例如 v1.43.0 的 MIGRATION.md 首行即标注Generated. DO NOT MODIFY说明其内容来自上游语义约定而非手工维护。2.3 更新全仓库 semconv 导入新包生成后需要把代码库中所有旧版 semconv 导入切换为新版本// 修改前 semconv go.opentelemetry.io/otel/semconv/v1.37.0 go.opentelemetry.io/otel/semconv/v1.37.0/otelconv // 修改后 semconv go.opentelemetry.io/otel/semconv/v1.39.0 go.opentelemetry.io/otel/semconv/v1.39.0/otelconv随后执行make全量编译并跑测试确保没有编译或测试失败。值得注意的是OTel Go 会长期保留历史 semconv 版本包供用户按需引用如 buildkit 中util/tracing及detect/resource.go即引用了 semconv 属性因此升级导入针对的是仓库内部自用代码而不是删除旧版本包。属性变更的处理部分 semconv 版本会新增、重命名或合并属性attribute甚至改变属性值语义。处理原则是优先改用新约定中接替旧属性的新属性与语义约定保持一致但旧属性仍可按OTEL_SEMCONV_STABILITY_OPT_IN环境变量的配置继续输出以保证稳定性过渡期内的兼容。此类迁移的跟踪与实施可参考上游 issue仓库文档中给出示例 #7806。这正是依赖 OTel 的上游项目如 buildkit在升级 OTel 版本时最需要关注的破坏性变更来源。2.4 Go contrib 仓库 linter 同步OTel Go 生态还包括opentelemetry-go-contrib仓库。主仓库升级 semconv 后需要在 contrib 仓库的.golangci.yml中把强制使用的 semconv 版本同步为新版本否则 contrib 代码的 lint 检查会与主仓库脱节。三、Breaking Changes 校验make goreleaseGo 模块一旦发布公共 API 的破坏性变更将直接影响下游所有依赖方。OTel Go 使用gorelease工具来自golang.org/x/exp/cmd/gorelease检测公共 API 是否有非预期的变化make gorelease从 Makefile 的实现看gorelease遍历所有 Go 模块目录OTEL_GO_MOD_DIRS对每个模块单独执行gorelease输出对比结果。发布者据此确认本次改动没有意外破坏公共 API工具本身的问题可在上游 Go 的 issue 跟踪页反馈文档给出 #26420。这一步是semantic versioning 承诺的机器化保障与 CHANGELOG.md 中大量标注⚠️ Breaking Change的条目互相印证——每个破坏性变更都必须有意识地进入 changelog而不是悄悄混入。四、contrib 仓库兼容性验证若本次主仓库改动会影响 contrib 仓库例如 semconv 升级、公共 API 变更必须按 contrib 仓库 RELEASING.md 中 Verify OTel changes 一节提供的步骤验证兼容性确认主仓库新版本不会让 contrib 代码编译失败或行为异常。五、Pre-Release确定模块集并准备发布分支5.1 规划版本并准备分支先确定本次要发布的模块集在 versions.yaml 中更新对应version字段提交到新分支同时更新各子模块的go.mod使其依赖即将发布的新版本为下一步正式发版做准备。5.2 执行make prereleasemake prerelease MODSETmodule set该 targetMakefile先运行verify-modsmultimod verify再通过 multimod 工具执行 prerelease。它会创建一个名为prerelease_module set_new tag的分支包含本次发布的所有版本改动。git diff ...prerelease_module set_new tag检查 diff 中所有模块版本号是否都已被提升为new tag确认无误后合并到你的预发布分支git merge prerelease_module set_new tag5.3 更新 Changelog这是发布过程中信息量最大的一步用如下命令查看自上一个 tag 以来的全部提交确保所有相关改动都被记录git --no-pager log --prettyoneline last tag..HEAD把Unreleased区段的所有条目迁移到新版本小节小节标题遵循[new tag] - date of release格式新小节必须放在!-- Released section --注释之下从而避免被后续脚本覆盖。这一点从 CHANGELOG.md 的实际结构可以验证第 9 行是## [Unreleased]紧随其后第 11-12 行是!-- Released section --注释再往下才是已发布版本小节更新文末的所有版本链接如[1.45.0/0.67.0/0.21.0/0.0.18]: https://...这类引用式链接定义。值得说明的是OTel Go 的 changelog 采用多模块联合版本号标题如[1.45.0/0.67.0/0.21.0/0.0.18] - 2026-08-03对应各模块集各自的版本阅读者需要按模块集分别解读。5.4 提交 PR将改动推送到 upstream 并创建 Pull RequestPR 描述中必须包含从 CHANGELOG.md 整理出的本次发布要点。六、Tag为合并后的提交打标签PR 合并后即可对主分支上的合并提交打 tag。此处有两个硬性约束必须使用与 Pre-Release 步骤相同的 tag否则版本状态会陷入损坏状态。只要在 pre-release 与 tag 之间不修改versions.yaml就不会出错Go 模块无法轻易删除错误 tag上游 Go issue #34189 记录了该限制错误打 tag 会导致难以善后仓库文档给出的教训可追溯至 issue #331。对每个要发布的模块集在合并提交的 commit hash 上执行make add-tags MODSETmodule set COMMITcommit hash只有当前工作目录HEAD不是正确提交时才需要显式传COMMITMakefile 中COMMIT默认值为HEAD。该 target 同样先跑verify-mods再执行 multimod 的tag子命令。随后把所有 tag含各子模块路径对应的 tag推送到 upstream 远程仓库注意是主仓库而非个人 forkgit push upstream new tag git push upstream submodules-path/new tag ...七、签名发布产物GPG 与 CNCF 合规为满足 CNCF 对发布产物的最佳实践要求需要对 GitHub tags 页面下载的.tar.gz与.zip归档进行 GPG 签名。签名前可用仓库文档指向的校验脚本核对归档内容。先获取自己的 GPG 密钥 IDgpg --list-secret-keys --keyid-formatlong输出中sec rsa4096/之后的 16 位字符串即为密钥 ID。然后设置环境变量并对两个归档分别做分离签名detached signatureexport VERSIONversion # 例如 v1.32.0 export KEY_IDyour-gpg-key-id gpg --local-user $KEY_ID --armor --detach-sign opentelemetry-go-$VERSION.tar.gz gpg --local-user $KEY_ID --armor --detach-sign opentelemetry-go-$VERSION.zip验证签名gpg --verify opentelemetry-go-$VERSION.tar.gz.asc opentelemetry-go-$VERSION.tar.gz gpg --verify opentelemetry-go-$VERSION.zip.asc opentelemetry-go-$VERSION.zip八、Release在 GitHub 创建发布最后在 GitHub 上为new tag创建 Release正文包含 changelog 中本次发布的所有 release notes。重要约束GitHub Release 一旦创建即不可变因此必须在创建 Release 时一并上传已签名的四个产物——.tar.gz、.tar.gz.asc、.zip、.zip.asc事后无法再追加或修改。九、Post-Release收尾与生态联动9.1 contrib 仓库联动发布主仓库发布验证通过后需要按 contrib 仓库自身的 RELEASING.md 流程发布一个基于新版本的上游 contrib release保持整个 OTel Go 生态版本一致。9.2 更新官网 Go 文档在 OpenTelemetry 官网的 Go 语言文档目录content/en/docs/languages/go下更新 Go 插桩文档重点是把文档中引用的包版本提升为刚发布的版本确保所有代码示例仍能编译、内容依然准确。9.3 关闭 Milestone发布完成后把所有本次修复的 issue 与合并的 PR 归入对应 milestone以便追溯每个版本包含的改动。可用仓库文档给出的 GitHub 搜索查询找出遗漏项未纳入任何 milestone 的已关闭 issue按更新时间倒序未纳入任何 milestone 的已合并 PR。全部归入后关闭 milestone最后勾选Version Releaseissue 的 todo 列表并关闭该 issue整个发布周期结束。十、给依赖方的实用启示尽管 RELEASING.md 是面向 OTel Go 维护者的流程文档但其揭示的机制对 buildkit 这类重度使用go.opentelemetry.io/otel的上游项目同样有参考价值版本号语义v1.x.y稳定 API、v0.x.y实验 API并行演进依赖方升级时应分别关注 sdk/trace/metric 与metric/x、sdk/log等模块的版本节奏破坏性变更集中出现在 changelog 的⚠️ Breaking Change条目升级前应重点扫描该标记semconv 版本升级往往伴随属性更名/合并可依据对应版本的 MIGRATION.md 评估迁移成本多模块 tag 模式意味着 go.mod 中引用的 exporter 子模块与主模块可能位于不同 taggo mod tidy与go get需按模块路径精确指定版本OTel Go 的semconv-generate、gorelease、prerelease等自动化环节表明多模块 Go 仓库的发版应尽量脚本化人工打 tag 和手工维护版本号是主要风险源。若需在自己的 Go 项目内查看 OTel Go 的完整发布源码可直接阅读仓库内 Makefile、versions.yaml 与 CHANGELOG.md它们共同构成了可复现、可审计的发布流水线。【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考