• 开发工具

本指南以 CONTRIBUTING.md 为核心骨架，结合 google/uuid（Go 模块路径为github.com/google/uuid，见 go.mod）仓库内的 release-please 配置、CI 工作流、API 兼容性检查、CHANGELOG.md 与各测试文件，系统讲解为该项目提交补丁（patch）与功能（feature）贡献时必须遵守的提交规范、测试要求、自动化发布机制与法律要求。读完你将掌握：如何写出符合规范的提交信息并配好测试用例、理解一次代码合并如何自动演变为一次版本发布，以及签署 CLA 的注意事项。

一、贡献定位：欢迎一切 patch 与 feature

项目在 CONTRIBUTING.md 开篇即表明态度：“We definitely welcome patches and contribution to this project!”——该项目对补丁和功能贡献持完全开放的态度。从 CONTRIBUTORS 文件可以看到，除原作者 Paul Borman 外，还有 bmatsuo、shawnps、theory、dansouza 等十余位贡献者先后参与，项目长期保持外部贡献驱动的演进模式，因此了解贡献规范对任何打算提交代码的开发者都是必要的前置工作。

仓库本身是一个纯粹的 Go 库（module github.com/google/uuid，无任何第三方运行依赖），核心功能是生成与解析基于 RFC 9562 和 DCE 1.1 的 UUID（见 README.md）。这也意味着绝大多数贡献都落在新增或改进 API、修复解析/生成逻辑、完善测试与文档这几类工作上，恰好与下文要讲的提交类型一一对应。

二、提交信息规范：必须遵循 Conventional Commits

CONTRIBUTING.md 提出的第一条硬性要求是：

Commits must be formatted according to the Conventional Commits Specification.

即所有提交信息必须符合 Conventional Commits（约定式提交）规范。这不是建议而是必须，因为它直接决定了下一节描述的 release-please 能否正确自动发布版本。

2.1 提交信息的基本格式

一个符合规范的单行提交信息形如：

<type>[optional scope]: <description>

其中type表示提交性质，常用的类型及其语义如下：

若提交包含破坏性变更（API 不向后兼容），需要在提交信息的正文或脚注中写明BREAKING CHANGE:，此时会触发major 版本号的提升。scope为可选的模块范围标识，例如feat(uuid): add NewV7FromReader这类带范围的写法同样被规范接受。

2.2 CHANGELOG.md 中的直接印证

release-please 会在发布时按提交类型自动归类生成变更日志，这一点在 CHANGELOG.md 中有清晰的实证：1.5.0 → 1.6.0 的版本跃迁来自feat类型的提交add Max UUID constant（对应 uuid.go 中新增的 Max UUID 常量），因此版本号落在 minor 位；同一版本内的fix typo in version 7 uuid documentation、Monotonicity in UUIDv7则被归入### Bug Fixes小节。可以看到 CHANGELOG 的### Features与### Bug Fixes小节正是按提交类型归类的结果，提交信息写得越规范，生成出的变更日志就越准确、越有可读性。

三、测试要求：尽量为改动附带测试用例

CONTRIBUTING.md 对测试的要求非常明确：

Always try to include a test case! If it is not possible or not necessary, please explain why in the pull request description.

即：提交改动时尽量附带测试用例；如果确实无法或无需编写测试，必须在 PR（Pull Request）描述中说明原因。对 google/uuid 这类以解析与位运算为核心的库来说，测试不仅是质量保障，更是版本发布前的安全网。

3.1 仓库的测试布局与运行方式

仓库中已有大量与源文件一一对应的测试文件：

贡献者在本地验证改动最直接的方式，就是运行与 CI 完全一致的命令：

go test -v ./...

这一命令正是 tests.yaml 中 CI 的实际执行步骤；该工作流会在 PR 指向master分支时触发，并在 Go 1.19、1.20.x、1.21 三个版本构成的矩阵上运行，确保库在不同 Go 版本下的行为一致。

3.2 参考仓库的测试写法：表驱动测试

新增功能时，推荐参考 uuid_test.go 中已经成熟的表驱动（table-driven）测试模式：先定义一个测试结构体（test{in, version, variant, isuuid}），再列出覆盖正常值、边界值与非法输入的用例表，最后用循环逐条断言。这种写法对解析类、校验类功能尤其高效——一份用例表即可同时覆盖格式正确性、版本位、变体位与错误分支，也是该项目自身长期采用的风格。

3.3 复杂场景下的“无法常规化测试”实例

“无法或无需编写测试”的情形在该仓库中同样存在实证。例如 seq_test.go 中的TestClockSeqRace是一段需要在多核环境下并发压测 1 分钟的回归测试，正常运行go test时会通过--regressions标志被跳过（go test -run TestClockSeqRace -regressions）。这正说明：有些测试开销大、依赖特殊环境，无法纳入默认测试集——此时在 PR 描述中向维护者说明“为什么没写常规测试、如何手动验证”，就是 CONTRIBUTING.md 要求的正确做法。

四、发布机制：release-please 自动化版本管理

CONTRIBUTING.md 用专门一节描述了项目的自动发布机制，这是它与普通“提交规范 + CLA”模板最大的不同点，也是理解整个贡献闭环的关键：

Commits that would precipitate a SemVer change, as described in the Conventional Commits Specification, will trigger release-please to create a release candidate pull request. Once submitted, release-please will create a release.

即：任何会引发 SemVer 版本变化的提交（即feat、fix或含BREAKING CHANGE的提交），都会触发 release-please 自动创建“发布候选 PR”（release candidate PR）；该 PR 一经合并，release-please 便会创建正式 release。

4.1 release-please 的仓库配置

仓库根目录的 release-please.yml 是这一机制的配置源头，全文仅两行：

handleGHRelease: true releaseType: go

• releaseType: go表示按 Go 模块的惯例管理版本：以vX.Y.Z作为发布标签，并根据 Go 模块语义决定是否提升主版本号；
• handleGHRelease: true表示由 release-please 直接创建 GitHub Release（而非仅生成标签或变更日志）。

4.2 一次发布的完整链路

结合 CHANGELOG.md 的记录，一次典型发布经历以下环节：

1. 维护者将符合 Conventional Commits 规范的feat/fix提交合并进master；
2. release-please 扫描提交历史，依据类型判断下一次版本号（feat升 minor、fix升 patch、BREAKING CHANGE升 major）；
3. release-please 自动创建 release candidate PR，其中通常包含对 CHANGELOG.md 的更新与版本号提升；
4. 该 PR 被合并后，release-please 即创建对应版本的 release。

CHANGELOG.md 中形如## 1.6.0 (2024-01-16)的版本条目，以及### Features、### Bug Fixes小节，都是 release-please 自动化产出的直接证据。

4.3 API 兼容性守护：apidiff 工作流

release-please 对 major 版本的判断依赖“破坏性变更”的识别，而这一判断并非只靠提交信息。仓库还配置了 apidiff.yaml：每当 PR 指向master时，CI 会安装golang.org/x/exp/cmd/apidiff，先对master生成 API 基线（uuid.baseline），再与 PR 分支的导出 API 对比，若存在不兼容变更（-incompatible检查产生输出）则 CI 直接失败。从该工作流的配置可以推断，它与 release-please 共同构成双保险：release-please 依据提交规范决定版本号，apidiff 则在代码层面把关“破坏性变更是否被如实声明”，防止 major 版本被误判。这也反过来提醒贡献者：涉及公开 API 签名变化的提交，必须如实标注BREAKING CHANGE。

五、法律要求：签署贡献者许可协议（CLA）

贡献流程的最后一项硬性要求是法律层面的：

In order to protect both you and ourselves, you will need to sign the Contributor License Agreement.

即贡献者需要签署 Google 的贡献者许可协议（Contributor License Agreement）。CONTRIBUTING.md 同时说明：如果你此前已为其他 Google 开源项目签署过 CLA，则无需重复签署——Google 的 CLA 是跨项目通用的，一个签名即可覆盖其名下所有开源项目。

签署 CLA 的目的在于同时保护贡献者与项目方：一方面确认贡献者对提交内容拥有相应权利，另一方面授予项目方使用、再分发这些代码的合法许可，避免后续出现版权或授权纠纷。这是几乎所有 Google 系开源项目贡献流程的标准前置步骤。

六、从 0 到 1 的贡献实操清单

综合 CONTRIBUTING.md 的全部要求与仓库 CI 配置，一次完整的贡献可以按以下清单推进：

1. 获取源码并建立分支：从仓库克隆后，基于master创建功能分支：

   git clone https://gitcode.com/gh_mirrors/uuid11/uuid git checkout -b feat/my-improvement

2. 编写代码与测试：修改对应源文件（新增功能参考 version4.go、version7.go 等实现文件的 API 风格），并按表驱动模式在对应*_test.go中补充用例。
3. 本地验证：运行go test -v ./...确保全部测试通过；涉及 V1 并发唯一性的场景可追加go test -run TestClockSeqRace -regressions验证回归（见 seq_test.go）。
4. 规范提交：提交信息按 Conventional Commits 格式书写，例如：

   git commit -m "feat: add support for parsing custom format"

   破坏性变更必须附BREAKING CHANGE:说明。

5. 提交 PR 并完善描述：在 PR 描述中总结改动；若未包含测试用例，务必解释原因。
6. 等待 CI 与审查：确认 tests.yaml 的多版本测试与 apidiff.yaml 的 API 兼容性检查全部通过。
7. 确认 CLA：确保已签署 Google CLA（或已为此前其他 Google 项目签署过）。

七、贡献者参考：仓库文件地图

为便于快速定位改动面，以下是贡献过程中最常涉及的仓库文件（均位于仓库根目录，路径以根目录为基准）：

• 贡献与发布规范：CONTRIBUTING.md、.github/release-please.yml
• 持续集成：.github/workflows/tests.yaml（单元测试矩阵）、.github/workflows/apidiff.yaml（API 兼容性检查）
• 发布产物与作者记录：CHANGELOG.md（release-please 生成）、CONTRIBUTORS
• 核心实现：uuid.go（UUID 类型、解析与错误定义）、version1.go、version4.go、version6.go、version7.go（各版本生成逻辑）、marshal.go、sql.go、null.go、time.go
• 测试对应：uuid_test.go、version6_test.go、sql_test.go、null_test.go、time_test.go、json_test.go、seq_test.go

把握住“Conventional Commits 决定版本语义、测试用例守护行为正确、release-please 完成自动化发布、CLA 保障法律合规”这四条主线，你就能顺畅地完成一次从提交到发布的完整贡献闭环。

• 开发工具