Moby 供应链视角：解读 cloud.google.com/go 的 Go 多模块版本发布流程

本篇技术文章基于 Moby 仓库中随代码一起分发（vendored）的 Google Cloud Go 客户端库发布文档 RELEASING.md 展开，讲解多 Go 模块仓库如何确定"该发哪个模块"、release-please 自动发布的工作机制，以及根模块与子模块的手动发布操作；读完之后，你既能掌握上游 Google Cloud Go 客户端的版本发布规则，也能理解 Moby 在 vendor/modules.txt 中锁定这些依赖版本时的语义来源。

为什么 Moby 仓库里会有一份"发布流程文档"

Moby 通过 Go 的 vendor 机制将运行期依赖完整快照进仓库。其中 cloud.google.com/go 这一组模块被 GCP 日志驱动使用——daemon/logger/gcplogs/gcplogging.go 直接导入 cloud.google.com/go/logging 来将容器日志转发到 Cloud Logging。上游库在 vendored 目录中不仅保留了代码，还保留了自身的 CHANGES.md、RELEASING.md 与 release-please 配置文件。这些文件对使用者同样有价值：它们精确说明了你所锁定的依赖版本是如何被切出来的，是理解依赖版本行为的第一手证据。

当前 Moby 锁定的版本可以在 vendor/modules.txt 中直接查到，每个 # 开头的行即一个独立模块及其版本：

模块	锁定版本
cloud.google.com/go（根模块）	v0.123.0
cloud.google.com/go/auth	v0.20.0
cloud.google.com/go/auth/oauth2adapt	v0.2.8
cloud.google.com/go/compute/metadata	v0.9.0
cloud.google.com/go/logging	v1.19.1
cloud.google.com/go/longrunning	v1.2.0

这与 RELEASING.md 中"各模块完全独立发布、互不影响"的规则一一对应：每个模块拥有独立的版本线。例如根模块的最新版本记录在 vendor/cloud.google.com/go/CHANGES.md（最新为 0.123.0，2025-09-18），而 logging 子模块独立演进到 vendor/cloud.google.com/go/logging/CHANGES.md 中的 1.19.1（2026-08-07）。

核心规则：如何确定该发布哪个模块

文档开篇给出的第一条规则是整套流程的基石：模块与库并不一一对应，而是对应一棵棵目录树；要发布某个文件的变更，就必须发布它的"最近祖先模块"。

上游仓库的完整模块清单（文档中通过 find . -name go.mod 枚举）包括：

$ cat `find . -name go.mod` | grep module
module cloud.google.com/go/pubsub
module cloud.google.com/go/spanner
module cloud.google.com/go
module cloud.google.com/go/bigtable
module cloud.google.com/go/bigquery
module cloud.google.com/go/storage
module cloud.google.com/go/pubsublite
module cloud.google.com/go/firestore
module cloud.google.com/go/logging
module cloud.google.com/go/internal/gapicgen
module cloud.google.com/go/internal/godocfx
module cloud.google.com/go/internal/examples/fake
module cloud.google.com/go/internal/examples/mock
module cloud.google.com/go/datastore

其中 cloud.google.com/go 是仓库根模块，其余均为子模块。文档给出两个典型判断案例，值得逐字掌握：

1. 变更位于 bigtable/bttest/inmem.go：最近祖先模块是 cloud.google.com/go/bigtable，因此应发布 bigtable 子模块的新版本。
2. 变更位于 asset/apiv1/asset_client.go：该路径下不存在更深的 go.mod，最近祖先就是根模块 cloud.google.com/go，应发布根模块。

文档特别强调一条容易误解的独立性原则：发布根模块不会影响任何子模块，反之亦然，两者完全独立发布。这也解释了为什么 tag 命名要区分——根模块用 vX.Y.Z，子模块用 LIB/vX.Y.Z（如 logging/v1.19.1）——这正是 Moby 的 vendor/modules.txt 中六个版本互不相关的由来。

前置门槛：测试失败会阻塞发布

在讨论具体发布动作之前，文档设定了一条硬性前置条件：

如果 Kokoro 构建中存在任何测试失败，发布会被阻塞，直到失败被解决。

并且这条规则在手动发布流程中被再次重申——即使失败出现在与待发布模块无关的其他子模块中，也必须先修复。这实际上将"全仓库 CI 绿"设为任何版本切出的准入条件，避免把破坏性变更随 tag 一起固化为公开版本。

自动发布：release-please 驱动的标准流程

仓库当前已切换到由 release-please 完成 cloud.google.com/go 根模块及所有子模块的自动发布。vendored 目录中保留了完整的发布配置，可以直接佐证文档描述：

• vendor/cloud.google.com/go/release-please-config.json：根模块配置，指定 "release-type": "go-yoshi"、"separate-pull-requests": true（每个模块独立开 PR）、"include-component-in-tag": false（根模块 tag 不带组件前缀，即纯 vX.Y.Z），并启用 sentence-case 插件规范 release note 文案；
• vendor/cloud.google.com/go/release-please-config-individual.json 与 vendor/cloud.google.com/go/release-please-config-yoshi-submodules.json：分别覆盖"独立子模块"与"Yoshi 同步子模块"两类子目录，与 tag 命名规则（LIB/vX.Y.Z）配套。

标准自动发布流程为四步：

1. 等待发布 PR。当存在尚未发布的变更时，release-please 会自动开一个标题形如 chore: release X.Y.Z（根模块）或 chore: release datastore X.Y.Z（datastore 子模块）的 pull request，X.Y.Z 即待发布的下一个版本号。
2. 检查持续构建。若最近一次构建存在失败，先解决失败再继续（无论失败是否发生在待发布子模块中）。
3. 审查 release notes。notes 由上一次发布以来所有已合并 commit 的标题自动生成；如需修改，直接编辑发布 PR 中的变更内容即可。
4. 批准并合并 PR。合并即完成切版：更新 CHANGES.md、用对应版本号给合并 commit 打 tag，并创建一个从 CHANGES.md 拷贝内容的 GitHub Release。

整个流程中人工只做"审查 + 合并"两个动作，版本号递增、changelog 生成、tag 推送全部自动化，这是当前推荐的主路径。

手动发布流程（根模块）：自动化失效时的兜底方案

当自动发布未按预期工作时，文档给出了完整的手动切版步骤（以 $CV 表示当前最新版本，$NV 表示新版本）：

1. 检查持续构建，存在失败则先修复；
2. 进入 google-cloud-go/ 仓库，切到 main 分支并 git pull；
3. 运行 git tag -l | grep -v beta | grep -v alpha 查看全部已有 release tag。当前最新 tag $CV 是最大的一个，形如 vX.Y.Z。注意忽略所有 LIB/vX.Y.Z 形式的 tag——那是特定子模块的 tag，不属于根模块；
4. 在 main 上运行 git log $CV... 列出上次发布以来的全部变更。注意：必须人工过滤掉子模块目录中的变更——git log 会显示子模块的改动，但它们不属于根模块的发布范围；
5. 编辑 CHANGES.md，写入变更摘要；
6. 在 internal/version/version.go 中把 const Repo 更新为当天日期（格式 YYYYMMDD）；
7. 在 internal/version 目录运行 go generate 重新生成版本文件；
8. 提交变更（忽略自动生成的 .go-r 文件），推送到个人 fork，创建标题为 chore: release $NV 的 PR；
9. 等待 PR 被评审合并。合并后，且期间不再合并任何其他 PR： a. 切到 main；b. git pull；c. 打 tag：git tag $NV；d. 推送 tag：git push origin $NV；
10. 更新 releases 页面，内容从 CHANGES.md 复制。

其中第 6、7 步体现了一个值得注意的工程细节：该仓库的版本号并非纯语义化版本，还内嵌了一个"仓库快照日期"（YYYYMMDD），每次发布都要先改常量再 go generate，保证版本字符串可追溯到具体提交日期。

手动发布流程（子模块）：以 datastore 为例

子模块的手动发布流程与根模块同构，但有三处关键差异——文档以 cloud.google.com/go/datastore 为例说明（实际执行时按目标子模块替换路径）：

1. 检查持续构建，规则同上；
2. 切到 main 并 git pull；
3. 运行 git tag -l | grep datastore | grep -v beta | grep -v alpha 查看该子模块的全部发布 tag。最新版本 $CV 形如 datastore/vX.Y.Z，同样忽略 beta/alpha 标签；
4. 运行 git log $CV.. -- datastore/——注意这里用路径过滤限定只看该子模块目录的变更（对比根模块流程需人工过滤子模块变更，此处恰好相反，是机器辅助过滤）；
5. 编辑 datastore/CHANGES.md 写入变更摘要；
6. 在 internal/version 运行 go generate；
7. 提交（忽略 .go-r 文件）、推 fork，创建标题为 chore(datastore): release $NV 的 PR；
8. PR 合并后、期间不再合并其他 PR 的前提下：切 main → git pull → git tag $NV → git push origin $NV；
9. 更新 releases 页面，内容取自 datastore/CHANGES.md。

对比两套手动流程可以发现，子模块发布不需要修改 internal/version/version.go 的日期常量（那是根模块版本字符串的一部分），tag 前缀（datastore/v... vs v...）与 changelog 文件位置（datastore/CHANGES.md vs CHANGES.md）是唯一的路径性差异，其余"合并 PR 后立刻打 tag 并保证 tag 指向的提交干净"的纪律完全一致。

对 Moby 使用者的实际意义

理解上游发布流程后，回到 Moby 侧可以得出三条实用结论：

1. 版本是独立坐标而非整体快照。升级 vendor/modules.txt 中 cloud.google.com/go/logging 到新版本，不会连带改变根模块 v0.123.0 的语义——上游对两者的发布是完全解耦的；
2. tag 前缀即模块边界。看到 logging/v1.19.1 应理解为"logging 子模块第 1.19.1 版"，而不是根模块版本；Moby 的 vendor 快照正是按这套 tag 语义锁定的；
3. CHANGES.md 是可审计的发布台账。vendored 的 vendor/cloud.google.com/go/CHANGES.md 与 vendor/cloud.google.com/go/logging/CHANGES.md 保留了逐版本的特性与修复清单（例如 logging 1.19.1 修复了元数据探测挂起的 HTTP 超时问题），排查 GCP 日志驱动行为时可直接对照锁定版本查阅。

整套流程的设计思想可以概括为一句话：用"最近祖先模块"规则划定发布边界，用 release-please 的"PR 合并即切版"把发布变成一次普通代码评审，再用"CI 全绿才可发 tag"守住质量下限——这也是任何多模块 Go 仓库都可以借鉴的发布治理范式。