企业官网建设流程全解析

• 云原生
• 开发工具
• DevOps
• 容器编排

导读：本仓库以 vendor 方式嵌入了go.opentelemetry.io/otel作为间接依赖（见 go.mod），本文以该依赖自带的 VERSIONING.md 为主线，系统讲解 OpenTelemetry Go 项目的版本管理策略——包括语义化导入版本（Semantic Import Versioning）、v0 实验模块与 v1+ 稳定模块的划分、所有稳定模块统一版本号的"同步发布"机制，以及项目与 contrib 仓库之间相互制约的发布节奏。读完本文，你将能准确理解 Go 模块多包仓库的版本号含义，正确书写go get/require中的/vN路径与@vN版本号，并看懂versions.yaml中 stable/experimental 模块组的划分逻辑。

一、为什么需要一份版本化策略文档

OpenTelemetry Go（go.opentelemetry.io/otel）是一个典型的"多模块仓库"（multi-module repository）：单仓库内同时存在trace、metric、baggage、sdk及大量 exporter 等数十个独立 Go module。它们之间存在复杂的相互依赖关系，如果每个模块各自随意发布版本，会带来两个突出问题：

1. 依赖地狱：某模块升版后，依赖它的其他模块无法判断新版本是否向后兼容；
2. 遥测语义不稳定：若稳定版 instrumentation 产生的遥测数据格式随意变化，依赖这些数据的告警规则和监控看板会被无声破坏。

因此该仓库专门编写了 VERSIONING.md，其核心目标（文档开头即阐明）是：为使用者提供一个稳定、安全且有价值的代码库。本文后续所有规则都围绕这一目标展开。

补充背景：本仓库（DevSpace）将go.opentelemetry.io/otel及otel/metric、otel/trace、otel/sdk、otel/exporters/otlp/otlptrace等模块以v1.36.0/v1.34.0版本 vendored 到vendor/目录下（见 go.mod），并以// indirect标注。这也意味着：理解这份版本策略，是安全升级 vendored 依赖的前提。

二、基础规则：Go Modules 与语义化导入版本

策略文档首先确立了基调：本项目的版本管理遵循 Go 社区使用 Go Modules 的惯用做法，具体包含以下两层：

2.1 遵循 semver 2.0，但有一个关键例外

版本号本身遵循 semver 2.0 规范，唯一例外是：

Warning: methods may be added to this interface in minor releases.

即：导出的 API 接口允许在 minor 版本（次版本）发布时新增方法。所有适用此例外的导出接口，其公开文档中都必须包含上述警告段落。

为什么需要这个例外？因为 API 接口（如TracerProvider、MeterProvider）是 instrumentation 代码与 SDK 之间约定的"契约"，SDK 可能需要在 minor 版本中演进能力。从源码看，这条规则已经落实到代码注释中——例如 trace/provider.go 中的TracerProvider接口和 metric/meter.go 中的MeterProvider接口都带有同样的警告字样。同时这些接口都内嵌了embedded.TracerProvider/embedded.MeterProvider（见 trace/provider.go 与 metric/meter.go），让接口实现者可以获得"未实现方法使用默认行为"的兼容性保障。

2.2 语义化导入版本（Semantic Import Versioning）

对于v2及以上的模块，主版本号必须写入模块路径：

• go.mod中的module声明与require指令，例如module go.opentelemetry.io/otel/v2、require go.opentelemetry.io/otel/v2 v2.0.1；
• 包导入路径，例如import "go.opentelemetry.io/otel/v2/trace"；
• go get命令，例如go get go.opentelemetry.io/otel/v2@v2.0.1。

注意上面例子中同时出现了/v2（路径部分）与@v2.0.1（版本部分）——理解口诀是：一旦模块名包含了/v2，那么凡是使用模块名的场景（require、import、go get）都必须带上/v2。而v0与v1模块则相反，不得在模块路径或导入路径中携带主版本号。

当前 vendored 的 otel 恰好处于v1.36.0，因此本仓库中的导入路径保持为go.opentelemetry.io/otel/trace这种无/vN的形式（参见 trace.go 的导入语句）。

三、v0 实验模块与 v1+ 稳定模块的划分逻辑

3.1 用模块封装信号与组件

仓库以 module 为单位封装"信号（signal）与组件（component）"：每个信号（trace / metric / log）以及每类组件（instrumentation、detector、exporter、propagator 等）都是独立模块。这种划分使得下游使用者可以只拉取自己需要的模块，而不用承担整个仓库的耦合。

3.2 主版本号即稳定性宣言

• 仍在活跃开发的实验性模块固定为v0：借用 semver 中"主版本 0（0.y.z）处于初始开发期，任何内容都可能随时变化，公共 API 不应视为稳定"的定义来向使用者明示不稳定性；
• 保证稳定公共 API 的成熟模块使用大于v0的主版本：是否"转正"为稳定版，由项目维护者逐案（case-by-case）评估决定，并非所有模块同时转正。

3.3 实验模块的版本递增规则

实验模块（v0）起始于v0.0.0，递增规则为：

• 不向后兼容的破坏性变更→ 递增 minor（次版本），如v0.14.0→v0.15.0；
• 向后兼容的变更→ 递增 patch（修订号），如v0.15.0→v0.15.1。

这在语义上与传统 semver 正好"错位"——v0 阶段的 minor 递增承担了稳定版中 major 递增才有的"破坏性变更"信号，读者务必注意。

四、核心机制：所有稳定模块共享同一版本号

这是整份策略中最具辨识度、也最影响使用者实践的一条规则：

所有使用相同主版本号的稳定模块，必须使用完全相同的完整版本号。

其衍生规则包括：

1. 为对齐而升版：某个稳定模块即使自身代码未变，也可能随着其他发生变更的稳定模块一起发布递增的 minor 或 patch 版本，以保持版本号一致；
2. 实验模块转正时的联动：当某个实验模块达到稳定标准时，会发布一个新的稳定版本并纳入该模块，新版本号递增 minor，且同时应用到所有既有稳定模块与刚转正的模块。

当前仓库中 versions.yaml 正是这一策略的落地产物：stable-v1模块组统一为v1.36.0，组内包含go.opentelemetry.io/otel、otel/metric、otel/trace、otel/sdk、otel/sdk/metric、otel/baggage等十余个模块；而experimental-metrics（如exporters/prometheus）保持v0.58.0，experimental-logs（log、sdk/log等）保持v0.12.0，experimental-schema保持v0.0.12——同一仓库内 v0 与 v1 共存、按组管理。对应地，仓库根目录 version.go 中Version()返回"1.36.0"，与stable-v1组一致。

五、关联的 contrib 仓库：稳定版联动的另一半

策略的第二大部分约束了配套的 opentelemetry-go-contrib 仓库（instrumentation、detector、exporter 等组件的官方集散地）：

1. 同样遵循 Go Modules 与语义化导入版本，v2+需在模块路径带/vN（例如go.opentelemetry.io/contrib/instrumentation/host/v2，go get go.opentelemetry.io/contrib/instrumentation/host/v2@v2.0.1）；
2. 稳定遥测的额外保证：稳定 instrumentation 产生的遥测数据也必须保持稳定且向后兼容，以免破坏既有告警与看板——这是纯 API 层面之外的、针对"数据契约"的约束；
3. 模块划分方式相同：同样以v0表示实验模块，v1+表示成熟模块；且稳定的 contrib 模块不得依赖本项目的实验模块（防止不稳定 API 被"传染"到稳定模块）；
4. 版本对齐：与本项目同主版本的所有稳定 contrib 模块使用与本项目完全相同的版本号。当 contrib 中实验模块转正时，新稳定版本递增 minor，并同时应用到既有 contrib 稳定模块、本项目模块及新转正模块；
5. 发布节奏互相钳制：
   • contrib 稳定版须在本项目发布之后错峰发布（无硬性时间承诺，但应尽量接近）；
   • 在本项目发布之后、contrib 完成匹配的稳定版之前，本项目不得再发布新的稳定版；
   • 本项目发布稳定版后，contrib 仓库只能发布稳定版，不得再发其他版本。

这套"互为闸门"的机制，确保了从核心 API 到社区 instrumentation 的整个生态始终以同一节奏、同一版本号演进，下游用户可以放心地对齐升级。

六、发布流程的其他约定

• 所有发布都会创建GitHub Release；
• 所有 Go module 都会同步发布到Go package mirrors（如 proxy.golang.org），供全球go get/go install使用。

这两条确保了"版本号一致"之外，实际拉取体验也一致。

七、示例：从 v0.14.0 到 v1.1.0 的完整版本生命周期

文档用一个简化模型（只保留otel、otel/trace、otel/metric、otel/baggage、otel/sdk/trace、otel/sdk/metric六个模块）完整演示了策略的执行过程，值得逐步复刻：

7.1 起点：全部处于 v0.14.0 实验期

六个模块都是v0.14.0。此时otel/trace、otel/baggage、otel/sdk/trace达到稳定评估标准，而otel/metric、otel/sdk/metric仍在活跃开发；otel模块同时依赖otel/trace与otel/metric。

7.2 第一次转正：发布 v1.0.0-RC1 / RC2

先把otel重构、去掉对otel/metric的依赖，使其可独立转正。随后发布候选版本：

• otel、otel/trace、otel/baggage、otel/sdk/trace→v1.0.0-RC1
• otel/metric、otel/sdk/metric→ 维持v0.14.0

发现otel/trace存在若干需要"破坏性修复"的问题后，二次发布v1.0.0-RC2——注意所有模块版本同步递增，这正是"统一版本号"规则的体现。

7.3 正式稳定：v1.0.0

RC 评估通过后，发布v1.0.0（六个模块中四个转正）。由于 Go 工具链与模块系统遵循 semver 的版本优先级定义，v1.0.0会被正确解析为 RC 系列的继任版本。

7.4 开发继续：稳定版与实验版并行演进

此时otel/metric需要发布破坏性 API 变更、otel/baggage需要发布小 bug 修复，于是同时发布：

• 稳定组otel/otel/trace/otel/baggage/otel/sdk/trace→v1.0.1
• 实验组otel/metric/otel/sdk/metric→v0.15.0

关键观察点：稳定模块的 patch 版本（v1.0.1）与实验模块的 minor 版本（v0.15.0）分别承载了各自的"破坏性"信号；而otel/sdk/metric（依赖otel/metric）虽然策略未强制要求，也随之上调到v0.15.0——文档明确承认这是合理的耦合联动。

7.5 第二个信号转正：v1.1.0

otel/metric与otel/sdk/metric达到稳定标准后，otel模块重新整合进otel/metric，先发布v1.1.0-RC1（六个模块全部对齐），评估通过后正式发布v1.1.0。minor 版本从 1.0 升到 1.1，正是为了标识"新增了一个信号（metrics）"。

这个示例完整呈现了策略的三条要义：实验/稳定分级管理、稳定模块版本强制对齐、以及"新增稳定信号靠 minor 版本表达"。

八、对 DevSpace 使用者的实战启示

结合本仓库现状，落地建议如下：

1. 升级 vendored otel 时先看版本组：本仓库使用的v1.36.0属于stable-v1组（versions.yaml），升级时应同时关注组内otel/metric、otel/trace、otel/sdk等模块是否同步升级，避免混用不同 minor 版本造成隐性不兼容；
2. 警惕 minor 版本中的接口方法新增：TracerProvider、MeterProvider等接口允许在 minor 版本新增方法，但仓库已通过embedded内嵌类型为接口实现者提供了默认行为兜底（见 trace/provider.go），自定义实现者应保留该内嵌类型；
3. 不要在稳定遥测上做破坏性修改：如果应用基于 otel 输出遥测数据并配置了告警，升级依赖后应回归验证数据语义，因为 contrib 稳定 instrumentation 的遥测数据同样受"稳定且向后兼容"约束；
4. /vN路径只属于 v2+：当前 v1 版本不需要在导入路径加/vN；若未来主版本升级到 v2，则本仓库的导入路径、go.modrequire 与go get全部需要带上/v2后缀。

九、延伸阅读

• 版本化策略原文：本文所有规则的权威出处；
• versions.yaml：当前各模块组（stable-v1 / experimental-metrics / experimental-logs / experimental-schema）的版本快照；
• version.go：Version()返回当前发布版本1.36.0；
• RELEASING.md：配套发布流程——用make prerelease MODSET=...生成预发布分支、make add-tags MODSET=...打 tag、make gorelease校验公共 API 无意外变更，并以make verify-mods校验versions.yaml的一致性；
• Makefile：prerelease与add-tags两个发布目标的确切定义（依赖verify-mods与 multimod 工具）；
• trace/provider.go 与 metric/meter.go：「minor 版本可新增接口方法」警告与embedded内嵌类型的实际落点；
• go.mod：本仓库对go.opentelemetry.io/otel系列模块的 vendored 依赖声明（v1.36.0/v1.34.0，均标注// indirect）。

• 云原生
• 开发工具
• DevOps
• 容器编排