时序数据库后端数据存储可观测性云原生【免费下载链接】mimirGrafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus.项目地址https://gitcode.com/gh_mirrors/mimir/mimir点击查看免费下载本文以 Mimir 仓库内 vendor 的开源依赖文档 RELEASING.md 为主线系统讲解 OpenTelemetry Goopentelemetry-go这一典型多模块 Go 仓库的完整版本发布流程包括 Semantic Convention 代码生成与升级、破坏性变更验证、prerelease与add-tags多模块打标、GPG 产物签名以及发布后的收尾工作。读完本文你将掌握一套可直接复用的 Go 多模块发布工程方法论并能在遇到semconv版本升级、多模块版本号同步、CHANGELOG 维护等场景时按图索骥。一、背景为什么一个多模块仓库需要专门的发布流程opentelemetry-go 不是一个单一 Go module而是由go.opentelemetry.io/otel主模块以及大量子模块sdk、metric、trace、各类 exporter 等组成的多模块仓库。这类仓库发布时有三个天然难点多个模块需要同步升版本且稳定版stable与实验版experimental各自有独立的版本序列semconvSemantic Conventions包会随上游规范频繁换代每个版本生成独立子包历史版本需要长期并存、不能互相覆盖Go module 版本一经发布就不可撤销标签、产物签名都必须一次性正确。发布流程文档即本文讲解的主体正是为应对这些难点而设计其每一环节都在仓库中能找到对应的实现证据。在 Mimir 仓库中这份文档位于vendor/go.opentelemetry.io/otel/目录下是随依赖一起 vendor 进来的上游资料当前 go.mod 引用go.opentelemetry.io/otel v1.47.0、go.opentelemetry.io/otel/sdk v1.47.0、go.opentelemetry.io/otel/trace v1.47.0使用的正是 vendor 目录内的这份代码。因此本文既能帮你理解上游 OpenTelemetry 的发布机制也能帮你理解 vendor 进来的依赖是如何演进的。二、发布第一步创建Version Releaseissue正式动手之前先创建一个Version Releaseissue 用于跟踪整个发布流程。文档明确要求用它来承载发布过程中的待办清单——后续每个步骤semconv 升级、prerelease、打标签、签名、正式 release、关闭 milestone 等完成后都在该 issue 中逐项核对直到最后一步“关闭 issue”。这样做的价值在于多模块发布跨越多次 PR、多个人工操作如果没有一个可见的跟踪载体很容易漏掉诸如“忘记给某个子模块打标签”“忘记把 merged PR 归入 milestone”这类环节。三、Semantic Convention 升级每次发布几乎都要先升级semconv包因为 OpenTelemetry Semantic Conventions 规范会持续演进产生新的语义约定版本。3.1 生成新的 semconv 子包semconv-generate新版本的规范意味着semconv包需要重新生成。文档给出的做法是使用semconv-generatemake targetexport TAGv1.30.0 # Change to the release version you are generating. make semconv-generate # Uses the exported TAG.关键在于TAG环境变量必须先行设置make semconv-generate会读取这个变量来定位要生成的规范版本。生成完成后仓库中会出现一个新的子包semconv/TAG例如semconv/v1.30.0。结合仓库源码可以看到该 target 的完整实现Makefile开头会强制校验TAG已设置[ $(TAG) ] || ( echo TAG unset: ...; exit 1 )未设置会直接报错退出生成工具是weaverDocker 镜像版本从dependencies.Dockerfile中解析见WEAVER_IMAGE : ...它从上游 semantic-conventions 仓库的对应 tag 下载[model]注册表通过 Docker 挂载本仓库的semconv/templates模板目录与semconv/${TAG}输出目录以--param tag$(TAG)传入版本号最后调用仓库内置的semconvkit工具$(SEMCONVKIT) -semconv semconv/ -tag $(TAG)完成收尾整理。在 Mimir 仓库的 vendor 目录中可以看到这种“多版本并存”的产物结构semconv/下同时存在v1.18.0、v1.21.0、v1.26.0、v1.37.0、v1.41.0、v1.43.0等多个版本子包见 semconv 目录。每个版本子包内都带有独立的MIGRATION.md、README.md、schema.go等文件例如 v1.43.0 的 MIGRATION.md 开头即说明“v1.43.0包可以作为v1.42.0的 drop-in 替代”。生成之后文档要求先确认内容无误再提交 Pull Request 引入该新增包同时更新CHANGELOG.md- 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/19b9778be992bd36d330a1c02a18181f) for information on how to upgrade from go.opentelemetry.io/otel/semconv/PREVIOUS VERSION. (#PR_NUMBER)Tip:将NEW VERSION与PREVIOUS VERSION替换为实际的发布版本与上一版本。该条目的具体迁移说明指向 MIGRATION.md 这一相对路径在仓库根目录下对应vendor/go.opentelemetry.io/otel/semconv/版本/MIGRATION.md。3.2 更新全代码库的 semconv import新 semconv 子包生成后要把代码库中所有 semconv 引用统一升级到新版本// Before semconv go.opentelemetry.io/otel/semconv/v1.37.0 go.opentelemetry.io/otel/semconv/v1.37.0/otelconv // After semconv go.opentelemetry.io/otel/semconv/v1.39.0 go.opentelemetry.io/otel/semconv/v1.39.0/otelconv注意这里的 import 路径是带版本号的模块路径如.../semconv/v1.39.0升级本质上是替换路径中的版本段。完成后运行make检查是否有编译或测试失败。3.3 处理属性变更并非所有 semconv 版本升级都只是路径替换。某些版本会新增属性或影响当前正在使用的属性——从简单重命名到复杂的“合并属性”“修改属性取值”都有可能。文档要求代码应更新到取代旧属性的新属性上以遵循语义约定但遗留属性仍可通过OTEL_SEMCONV_STABILITY_OPT_IN环境变量继续输出这是迁移期的兼容通道迁移如何跟踪与执行可参考 opentelemetry-go 仓库中 issue #7806 给出的实际示例。这意味着升级 semconv 时不能机械替换 import还要审视属性层面是否发生了语义变化必要时保留双轨输出。3.4 Go contrib linter 更新主仓库升级 semconv 后配套的opentelemetry-go-contrib仓库也要同步更新其.golangci.yml强制要求使用新的 semconv 版本保证生态内代码不落后于主仓库的语义约定版本。四、破坏性变更验证make gorelease发布前必须确认公共 API 没有意外变化。文档给出的手段是make gorelease该命令会运行gorelease来自golang.org/x/exp/cmd/gorelease做 API 兼容性检查。从 Makefile 可以看到这个 target 会对OTEL_GO_MOD_DIRS中定义的每一个子模块目录依次执行gorelease确保所有模块的公共 API 变更都处在预期范围之内。若发现非预期的破坏性变更应在发布前修正或走弃用流程。五、验证对 contrib 仓库的兼容性如果主仓库的改动会影响 contrib 仓库还需按 contrib 仓库的RELEASING.md中 “Verify OTel changes” 步骤做一次交叉验证。这一步的本质是在发布主仓库之前先在消费方contrib验证兼容性避免发布后发现生态代码无法编译或行为不一致。六、Pre-Release版本号与变更日志这是整个流程中手工操作最密集的阶段文档把它拆成 5 个子步骤。6.1 更新versions.yaml并提交新分支首先决定要发布哪些 module set然后在versions.yaml中更新它们的版本号并把该改动提交到新分支。versions.yaml是这套多模块机制的“版本中枢”。仓库中的 versions.yaml 展示了它的完整结构module-sets把模块分组定义例如stable-v1版本v1.47.0包含otel、sdk、metric、trace、各 exporter 等一组模块、experimental-metricsv0.69.0、experimental-logsv0.23.0、experimental-traces、experimental-schemaexcluded-modules排除不需要随版本号同步发布的模块如内部工具模块modules为个别模块指定version-refs指向它们内部记录版本号的文件如./internal/version.go供版本同步工具核对。可见稳定版与实验版模块组使用不同的版本序列v1.x与v0.x这就是为什么发布时要以 module set 为单位、逐个组处理。6.2 运行prereleasetargetmake prerelease MODSETmodule set该命令会创建一条名为prerelease_module set_new tag的分支承载所有版本改动。源码层面Makefile 要求必须先运行verify-mods基于 multimod 工具核对模块定义并且强制MODSET已设置否则报错退出。6.3 核对改动并合并git diff ...prerelease_module set_new tag核对结果应显示所有模块的版本都被改成了new tag。确认无误后把该分支合并进你的 pre-release 分支git merge prerelease_module set_new tag6.4 更新 CHANGELOG更新 CHANGELOG.md 是本阶段最考究的一步文档给出了明确规范确保本次发布的所有相关改动都收录其中且措辞能让非贡献者也看懂。为核对改动可直接查看自上个 tag 以来的全部提交git --no-pager log --prettyoneline last tag..HEAD把Unreleased下的改动移入新段落段落标题遵循[new tag] - date of release格式新段落必须放在 released section 的注释标记!-- Released section --之下这样它才会被后续流程“锁定保护”不会被未来的发布覆盖掉同步更新文件底部的所有相关链接。仓库里的 CHANGELOG.md 恰好展示了这一结构的真实形态## [Unreleased]在上紧接着是!-- Released section --注释与已发布段落如## [1.47.0/0.69.0/0.23.0/0.1.0] - 2026-10-02。配套的校验脚本 verify_released_changelog.sh 会提取!-- Released section --与!-- Released section ended --两个标记之间的内容做比对确保已发布段落不被篡改——这正是文档中“放在 released section 注释之下以受保护”的落地实现。6.5 推送并创建 PR把改动推送到 upstream 并创建 GitHub Pull RequestPR 描述中必须附上从 CHANGELOG 精选出的本次发布变更说明。七、打标签TagPR 合并后进入打标签阶段。这一步有两个硬性警告必须使用与 Pre-Release 阶段完全相同的 tag只要不在这两步之间改动versions.yaml就能保持一致否则仓库会处于损坏状态。Go module 版本一旦发布就几乎无法移除上游已有明确的 issue 记录推错版本会造成难以绕开的事故因此推送前必须反复确认版本正确。7.1 运行add-tagsmake add-tags MODSETmodule set COMMITcommit hashCOMMIT指向主分支上合并 PR 的那个提交。只有当本地HEAD不是正确提交时才必须显式提供COMMIT否则默认使用HEADMakefile 中COMMIT ? HEAD。7.2 推送标签标签要推送到 upstream 远端而非自己的 fork并且所有子模块的标签都要推送git push upstream new tag git push upstream submodules-path/new tag ...子模块的标签路径形如子模块目录/new tag例如sdk/v1.47.0、metric/v1.47.0。八、签名发布产物CNCF 合规要求为满足 CNCF 最佳实践发布产物必须做 GPG 签名。具体步骤从 tags 页面下载新 release tag 对应的.tar.gz与.zip两个归档签名前可用脚本核验归档内容查询自己的 GPG key IDgpg --list-secret-keys --keyid-formatlongkey ID 是sec rsa4096/之后的 16 位字符串。设置环境变量并对两个产物签名export VERSIONversion # e.g., 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--detach-sign生成的是独立.asc签名文件与归档一起分发便于下游独立验签。九、创建 GitHub Release最后一步是为new tag创建 GitHub Release发布说明应包含该版本在 CHANGELOG 中的全部 release notes。这里同样有一个不可逆约束GitHub Release 创建后不可修改签名产物.tar.gz、.tar.gz.asc、.zip、.zip.asc四个文件必须在创建 Release 时一并上传因为之后无法追加或修改。十、Post-Release发布后的收尾工作版本发布出去只是开始还有四项收尾工作10.1 发布 contrib 仓库验证通过后为使用该版本的contrib仓库做一次发布。10.2 更新官网 Go 仪表化文档更新 OpenTelemetry 官网中 Go instrumentation 的文档把文中引用的包版本 bump 到你刚发布的最新版本并确保所有代码示例仍能编译、准确无误。10.3 关闭 milestone把本版本修复的 issue 和合并的 PR 全部归入对应 milestone便于追溯“这个版本包含哪些变更”查找尚未归入 milestone 的已关闭 issue可用“无 milestone 已关闭 关联 PR”的搜索条件查找尚未归入 milestone 的已合并 PR可用“无 milestone 已合并”的搜索条件全部归入后关闭该 milestone。10.4 关闭Version Releaseissue当Version Releaseissue 中的待办清单全部完成关闭该 issue——整个发布周期至此结束。十一、发布流程速查清单阶段关键命令 / 操作产物或状态创建 issue创建Version Releaseissue待办跟踪清单semconv 升级export TAG...make semconv-generate更新 import更新 CHANGELOG新semconv/TAG子包 PR破坏性变更验证make gorelease各子模块 API 兼容性报告contrib 验证按 contrib 仓库 “Verify OTel changes” 执行生态兼容性确认Pre-Release更新versions.yamlmake prerelease MODSET...更新 CHANGELOGprerelease_module set_new tag分支 PR打标签make add-tags MODSET... COMMIT...推送主模块与所有子模块标签正确无误的 git tags签名GPG 签名.tar.gz/.zip.tar.gz.asc/.zip.ascRelease创建 GitHub Release 并上传 4 个签名产物不可变的正式发布Post-Releasecontrib 发布官网文档更新关闭 milestone关闭 issue周期闭环小结从这份 RELEASING.md 可以看到一个成熟的多模块 Go 项目把“发布”做成了高度工程化的流程用versions.yaml管理 module set 的版本中枢用semconv-generateweaver semconvkit见 Makefile流水线化生成规范代码用gorelease守护公共 API 兼容性用prerelease/add-tags保证所有子模块版本号与标签严格一致再用 GPG 签名和不可变的 GitHub Release 保障产物可验证、可追溯最后通过 milestone 与跟踪 issue 完成闭环。这套方法论不仅适用于 OpenTelemetry Go也可直接迁移到任何多模块 Go 仓库的发布实践中——只要把每一步的命令、校验与不可逆约束照单执行发布质量就能得到结构性保证。赞分享时序数据库后端数据存储可观测性云原生【免费下载链接】mimirGrafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus.项目地址https://gitcode.com/gh_mirrors/mimir/mimir点击查看免费下载相关推荐OpenTelemetry Go 多模块版本发布流程深度指南从 semconv 升级、模块集打 tag 到 GPG 签名OpenTelemetry Go 多模块版本发布流程深度指南从 semconv 升级、模块集打 tag 到 GPG 签名 本文以当前仓库 vendored 的容器编排云原生集群管理微服务OpenTelemetry Go 多模块发布全流程指南从 Semantic Convention 升级到 GPG 签名 ReleaseOpenTelemetry Go 多模块发布全流程指南从 Semantic Convention 升级到 GPG 签名 Release 导读 OpenTele后端企业应用OpenTelemetry Gogo.opentelemetry.io/otel发布流程全解从 semconv 升级、预发布到 GPG 签名与 ReleaseOpenTelemetry Gogo.opentelemetry.io/otel发布流程全解从 semconv 升级、预发布到 GPG 签名与 Relea云原生DevOps运维上一篇如何免费解锁123云盘完整会员功能面向普通用户的终极解决方案下一篇国家中小学智慧教育平台电子课本下载完整指南三步轻松获取PDF教材创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
