OpenTelemetry Go SDK 发布流程实战指南从语义约定升级到 GPG 签名发布【免费下载链接】inngestThe leading workflow orchestration platform. Run stateful step functions and AI workflows on serverless, servers, or the edge.项目地址: https://gitcode.com/GitHub_Trending/in/inngest本指南以本仓库中随依赖一并 vendored 的 vendor/go.opentelemetry.io/otel/RELEASING.md 为骨架完整还原 OpenTelemetry Go SDKgo.opentelemetry.io/otel从语义约定Semantic Conventions升级到版本预发布、打 Tag、GPG 签名、正式 Release 与发布后收尾的端到端流程。作为 inngest 这类深度使用 OTel 的 Go 项目理解这套流程不仅有助于跟踪上游版本演进本仓库当前锁定otel v1.43.0还能在需要为多模块 Go 仓库设计发布管线时直接复用其 make 目标与版本管理约定。读完本文你将掌握semconv-generate、gorelease、prerelease、add-tags等核心命令的正确用法以及 Go 模块发布中Tag 不可删除带来的红线约束。发布前的项目结构认知为什么需要一套仪式化流程OpenTelemetry Go 仓库不是单一 Go module而是由数十个相互依赖的子模块构成的多模块仓库。这一点从 vendor/go.opentelemetry.io/otel/versions.yaml 可以直观看到仓库按 module-sets 对模块进行分组每个集合共享同一个版本号module-sets: stable-v1: version: v1.43.0 modules: - go.opentelemetry.io/otel - go.opentelemetry.io/otel/exporters/otlp/otlptrace - go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc - go.opentelemetry.io/otel/metric - go.opentelemetry.io/otel/sdk - go.opentelemetry.io/otel/trace # ...stable-v1 集合共 16 个模块 experimental-metrics: version: v0.65.0 modules: - go.opentelemetry.io/otel/exporters/prometheus experimental-logs: version: v0.19.0 modules: - go.opentelemetry.io/otel/log - go.opentelemetry.io/otel/sdk/log # ... experimental-schema: version: v0.0.16 modules: - go.opentelemetry.io/otel/schema从该文件可见稳定模块集与实验模块集采用不同的版本号策略稳定集v1.43.0实验集v0.x而excluded-modules列出不需要打版本标签的内部工具模块。这种多模块 分组版本的结构决定了发布不能靠手工改go.mod而必须依赖一套由 make 目标驱动、由multimod工具执行的自动化流程——这正是 RELEASING.md 要解决的痛点。一个额外的背景约束让流程更加严格Go 模块的版本 Tag 一旦推送无法真正删除Golang 官方 issue #34189 明确说明这一点。打错标签会直接影响所有下游go get用户因此文档在多个环节反复强调版本号必须一致、发布前必须验证。第一步创建Version Releaseissue整个发布流程以创建一个Version Releaseissue 作为起点。该 issue 用于追踪发布过程中所有待办事项语义约定升级、breaking changes 验证、预发布、打 Tag、签名、发布、里程碑收尾等每一步完成后勾选对应条目直至最后关闭 issue。这是发布流程的总清单也是团队协作时的单一事实来源。第二步Semantic Convention 升级新版本的 [OpenTelemetry Semantic Conventions]语义约定规范意味着需要为semconv包生成新的代码。这是整个发布流程中技术含量最高的一步分为生成、导入更新、属性迁移三个子阶段。2.1 使用semconv-generate生成新包生成动作由semconv-generatemake 目标完成步骤为设置TAG环境变量为要生成的语义约定版本号在仓库根目录运行make semconv-generate。官方示例export TAGv1.30.0 # 改成你要生成的语义约定版本 make semconv-generate # 使用上面导出的 TAG该命令会在 vendor/go.opentelemetry.io/otel/semconv 下创建一个新的子包例如semconv/v1.40.0。本仓库 vendored 的目录中实际保留了v1.17.0、v1.20.0、v1.21.0、v1.37.0、v1.39.0、v1.40.0等多个历史版本每个版本都自带MIGRATION.md迁移文档、attribute_group.go、schema.go等生成产物印证了每次升级新增一个独立版本子包、旧版本保留供兼容的演进模式。从 vendor/go.opentelemetry.io/otel/Makefile 可以看到该目标的真实实现它首先强制校验TAG必须存在[ $(TAG) ] || ( echo TAG unset... ; exit 1 )然后通过docker run启动 OpenTelemetry 官方的weaver镜像执行registry generate从语义约定仓库的指定 Tag 拉取模型配合semconv/templates模板生成 Go 代码最后用semconvkit工具对生成产物做后处理$(SEMCONVKIT) -semconv $(SEMCONVPKG) -tag $(TAG)。生成完毕后应检查产物是否符合预期再提交 Pull Request 合入。同时需要更新 vendor/go.opentelemetry.io/otel/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/cdc90c540955da71ca95d7de58bac5bc) for information on how to upgrade from go.opentelemetry.io/otel/semconv/PREVIOUS VERSION. (#PR_NUMBER)Tip:将版本号改为与实际发布的版本一致。2.2 更新全仓库的 semconv 导入新 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 的下游消费者同样存在这类导入例如 pkg/telemetry/trace/tracer.go 与 pkg/telemetry/metrics/metrics.go 都通过semconv go.opentelemetry.io/otel/semconv/v1.20.0引用semconv.SchemaURL、semconv.ServiceNameKey等常量来构建资源与 Span 属性——上游发布新 semconv 版本后消费方按同样模式升级导入即可。2.3 处理属性变更某些 semconv 版本会新增、重命名甚至合并属性改变属性值的语义。迁移时应更新代码以使用取代旧属性的新属性遵循最新的语义约定同时遗留属性仍可根据OTEL_SEMCONV_STABILITY_OPT_IN环境变量的设置继续发射以实现稳定性渐进迁移。官方曾通过 issue #7806 记录此类迁移的跟踪与执行方式可作为复杂属性迁移的参考案例。2.4 Go contrib linter 更新升级 semconv 后还需要更新opentelemetry-go-contrib仓库的.golangci.yml强制其 lint 使用新的 semconv 版本保证整个生态的版本一致性。第三步Breaking changes 验证make gorelease发布前必须确认公共 API 没有出现非预期的破坏性变更。运行make gorelease该目标会对仓库内每个模块执行goreleasegolang.org/x/exp/cmd/gorelease对比上一个已发布版本与当前代码的公共 API 差异。从 Makefile 的实现看它通过$(OTEL_GO_MOD_DIRS:%gorelease/%)模式逐个进入每个 Go module 目录执行$(GORELEASE)输出格式为gorelease in DIR。若发现意外变更需在合并前修正。第四步验证 contrib 仓库兼容性如果主仓库的改动会影响 contrib 仓库必须先按 contrib 仓库 RELEASING.md 中 Verify OTel changes 一节的步骤验证兼容性确保生态内其他仓库不会被本次发布破坏。第五步Pre-Release 预发布预发布阶段负责把版本号变更与 CHANGELOG 准备成一份可评审的改动集。确定发布范围并更新版本先在 versions.yaml 中决定本次要发布的 module set 及其新版本号把该改动提交到一个新的分支。更新子模块的 go.mod 依赖让各个子模块的 go.mod 指向即将发布的新版本。运行prereleasemake 目标make prerelease MODSETmodule set它会创建一个名为prerelease_module set_new tag的分支承载所有发布相关改动。Makefile 中该目标实际执行$(MULTIMOD) prerelease -m ${MODSET}且前置依赖verify-mods$(MULTIMOD) verify校验模块配置若未设置MODSET环境变量会直接报错退出。验证改动git diff ...prerelease_module set_new tag确认所有模块的版本都已被更新为new tag确认无误后合并到预发布分支git merge prerelease_module set_new tag更新 CHANGELOG这是对下游用户最可见的一步规范包括确保本次发布的所有相关改动都已收录且使用非贡献者也能读懂的语言描述。可通过git --no-pager log --prettyoneline last tag..HEAD直接核对自上一个 Tag 以来的所有提交将所有Unreleased下的改动移动到新章节章节标题遵循[new tag] - date of release格式新章节必须放在!-- Released section --注释之下使其在未来发布时受到保护、不会被覆盖更新文末所有相关链接。关于已发布章节受保护这一点仓库中的 verify_released_changelog.sh 提供了自动化保障该脚本用awk分别提取基线版本与当前版本中!-- Released section --到!-- Released section ended --之间的内容并做diff一旦发现已发布章节被修改即报错退出防止发布历史被事后篡改。推送并创建 PR推送到 upstream 并创建 Pull RequestPR 描述中务必附上从 CHANGELOG 整理的发布要点。第六步打 Tag注意两个红线预发布 PR 被批准合并后就该给合并提交打版本标签了。文档在此强调两条IMPORTANT红线必须使用与 Pre-Release 阶段完全相同的 Tag。如果两者不一致仓库会处于损坏状态。只要在预发布与打 Tag 之间不修改versions.yaml就不会出问题。Go 模块的错误版本 Tag 无法移除官方 issue #34189一旦推送错误版本会导致严重后果官方曾因此遭遇事故见 issue #331。推送前务必确认版本正确。打 Tag 的命令为make add-tags MODSETmodule set COMMITcommit hash其中COMMIT是主分支上合并 PR 的那个提交哈希只有当当前工作目录的HEAD不是正确提交时才需要显式指定。Makefile 中该目标执行$(MULTIMOD) tag -m ${MODSET} -c ${COMMIT}默认COMMIT为HEAD。随后把所有标签推送到 upstream 远程注意是主仓库而非你的 fork且必须包含所有子模块的标签git push upstream new tag git push upstream submodules-path/new tag ...第七步签名发布产物CNCF 合规要求为满足 CNCF 最佳实践需要对发布产物做 GPG 签名。流程如下从 Tags 页面下载新 Tag 对应的.tar.gz与.zip两个归档签名前可用官方提供的 attest 脚本校验归档内容查询你的 GPG 密钥 IDgpg --list-secret-keys --keyid-formatlong密钥 ID 是sec rsa4096/或类似输出后面的 16 位字符串设置环境变量并对两个产物分别做分离式detached签名export 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第八步创建 GitHub Release最后为new tag在 GitHub 上创建 Release正文应包含本次发布在 CHANGELOG 中的全部发布说明。IMPORTANTGitHub Releases 一旦创建即不可变签名产物.tar.gz、.tar.gz.asc、.zip、.zip.asc四个文件必须在创建 Release 时一并上传之后无法补充或修改。第九步Post-Release 收尾正式发布后还有四项收尾工作发布 contrib 仓库确认无误后为依赖本次发布的 contrib 仓库按其 RELEASING.md 流程发布新版本。更新官网文档更新 OpenTelemetry 官网 Go instrumentation 文档content/en/docs/languages/go目录将引用的包版本提升到刚发布的版本并确保所有代码示例仍然可以编译、内容准确。关闭里程碑milestone把本次发布修复的所有 issue 与合并的 PR 归入对应里程碑——可用官方提供的两个 GitHub 搜索查询找出已关闭但未纳入里程碑的 issue 与已合并但未纳入里程碑的 PR——全部归入后关闭里程碑便于追溯每次发布包含的改动。关闭Version Releaseissue待 issue 中的 todo list 全部完成关闭该 issue整个发布周期结束。从发布者到消费者inngest 如何随 OTel 版本演进理解上游发布流程对本仓库这类重度 OTel 消费者同样有实际价值。当前仓库在 go.mod 中锁定了go.opentelemetry.io/otel v1.43.0及其子模块otel/trace、otel/metric、otel/sdk、otel/sdk/metric、otlptrace/otlptracegrpc等并通过 vendor 机制将源码固定在仓库内。当上游按上述流程发布新版本时消费方需要关注两类变更模块版本升级将go.mod中的版本号提升到新稳定集版本重新 vendor 后执行构建与测试对应上游流程中的更新 semconv 导入 make验证环节语义约定属性迁移上游发布新 semconv 版本如v1.40.0后消费方可以选择继续使用旧版本子包如当前 pkg/telemetry/trace/tracer.go 使用的semconv/v1.20.0保持稳定或按迁移文档升级到新版本——这正是 RELEASING.md 中新版本生成、旧版本保留、属性可迁移设计意图的体现。发布流程速查清单阶段关键动作核心命令/文件起点创建Version Releaseissue 追踪 todoissue语义约定升级生成新 semconv 包并更新导入export TAG... make semconv-generateversions.yamlBreaking changes 验证对比公共 APImake gorelease预发布更新版本号与 CHANGELOGmake prerelease MODSETmodule set打 Tag给合并提交打全部子模块标签make add-tags MODSET... COMMIT...git push upstream签名GPG 分离签名 tar.gz/zipgpg --local-user $KEY_ID --armor --detach-sign ...发布创建不可变的 GitHub Release附带.tar.gz/.asc/.zip/.asc收尾contrib 发布、官网文档、里程碑、关闭 issueCHANGELOG 与里程碑核对上述全流程的核心参考实现均可在 vendor/go.opentelemetry.io/otel/Makefilesemconv-generate、gorelease、prerelease、add-tags目标、vendor/go.opentelemetry.io/otel/versions.yamlmodule-sets 分组与 vendor/go.opentelemetry.io/otel/CHANGELOG.mdKeep a Changelog 格式与 Released section 保护中进一步研读。【免费下载链接】inngestThe leading workflow orchestration platform. Run stateful step functions and AI workflows on serverless, servers, or the edge.项目地址: https://gitcode.com/GitHub_Trending/in/inngest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考