etcd 贡献者开发指南：从环境搭建、测试验证到 Pull Request 的完整工作流

本文基于 etcd 仓库根目录的 CONTRIBUTING.md 展开，系统讲解 etcd 项目的开源贡献全流程：如何挑选合适的任务、搭建本地开发环境（手动与 devcontainer 两种方式）、运行静态检查与三层测试套件、遵循提交信息规范，以及如何顺利完成 Pull Request 的审查与合入。读完本文，你可以独立搭建 etcd 开发环境、定位并修复 flaky 测试，并按照项目约定提交可被审查的代码变更。

贡献者工作流总览

etcd 采用 Apache 2.0 协议，通过 Pull Request 接受社区贡献。CONTRIBUTING.md 给出的标准贡献工作流包含六个环节：

1. Find something to work on —— 找到值得做的问题（含检查 flaky 测试）；
2. Set up development environment —— 搭建开发环境；
3. Implement your change —— 遵循 Golang 社区编码风格实现变更，通过静态分析与测试；
4. Commit your change —— 按约定格式撰写提交信息；
5. Create a pull request —— 创建 PR 并关联 issue；
6. Get your pull request reviewed —— 等待 CI 检查通过后请求维护者评审。

在动手之前，官方建议先了解项目本身：仓库内提供了 社区成员角色说明（Member / Reviewer / Maintainer 的职责、要求与晋升条件），Documentation/contributor-guide/ 目录下还有分支管理（branch_management.md）、cherry-pick 流程、发布流程等文档可供深入。此外仓库 README.md 中列出了社区联系方式，遇到问题时可以通过这些渠道联系维护者。

找到值得做的问题

etcd 的所有工作都在 GitHub issue 跟踪器中管理，issue 通过标签分类，便于按经验水平筛选任务：

标签	适用人群
good first issue	刚入门的贡献者
help wanted	已有一定贡献经验、想承担更实际工作的人
priority/important	资深贡献者，覆盖当时最相关的工作

如果上述标签下没有未分配的 issue，可以联系维护者（名单见根目录 OWNERS 文件中的 approvers 列表）请求做更多 issue 分诊。

修复 flaky 测试

项目长期需要帮助消除 flaky（不稳定）测试。etcd 使用 Kubernetes 的 Prow 基础设施运行 CI 作业，历史测试结果可在 testgrid 的 sig-etcd 视图查看，涵盖 presubmit / postsubmit / periodics 的 build、e2e-amd64、unit-test-amd64、verify 等作业。

如果在 testgrid 上发现 flaky 测试，建议按以下三步处理：

1. 先检查现有 issue 是否已经为这个测试开过问题单；若没有，创建一个带 type/flake 标签的 issue；
2. 在本地通过 Go 工具链中的 stress 命令复现，例如复现 TestPeriodicSkipRevNotChange（该测试位于 server/etcdserver/api/v3compactor/periodic_test.go）：

# 安装 stress 工具
go install golang.org/x/tools/cmd/stress@latest
cd server/etcdserver/api/v3compactor
# 编译测试
go test -v -c -count 1
# 用 stress 运行编译好的测试文件
stress -p=8 ./v3compactor.test -test.run "^TestPeriodicSkipRevNotChange$"

3. 复现之后进行修复。

搭建开发环境

etcd 支持两种开发方式：手动搭建本地环境，或使用 devcontainer 自动搭建。两种方式都有一个共同前提：官方仅支持 linux-amd64 架构。其他环境的 bug 报告通常会被忽略——支持新环境需要引入相应的测试与维护投入，而项目目前不具备这些条件。如果你的目标环境不受支持，可以在 issue 跟踪器中提交请求。

方式一：手动搭建本地环境

这是 etcd 传统的开发环境，支持最完善，并且向下兼容旧版本 etcd 的开发。步骤如下：

1. 克隆仓库；
2. 安装 Go：最低 Go 版本以 go.mod 第 3 行为准，当前为 go 1.26（并声明 toolchain go1.26.6）。仓库通过 make verify-go-versions（见 scripts/verify_go_versions.sh）校验各模块 Go 版本的一致性；
3. 安装构建工具（Debian 系发行版示例）：

工具	用途	安装方式
make	驱动构建	sudo apt-get install build-essential
protoc	生成 protobuf 代码，要求 v3.20.3	按操作系统下载安装
yamllint	校验 YAML	sudo apt-get install yamllint
jq	JSON 处理（BOM/依赖检查脚本依赖）	sudo apt-get install jq
xz	解压下载的工具包	sudo apt-get install xz-utils

4. 验证环境：运行 make build 确认工具链完整。

make build 默认以 -v 模式运行；如需追加构建参数，可设置环境变量 GO_BUILD_FLAGS，例如：

GO_BUILD_FLAGS="-buildmode=pie" make build

从 Makefile 可以看到，build 目标实际会向 scripts/build.sh 注入 GO_BUILD_FLAGS="${GO_BUILD_FLAGS} -v -mod=readonly"，其中 -mod=readonly 保证构建过程中不会隐式修改 go.mod / go.sum——测试脚本 scripts/test.sh 同样通过 export GOFLAGS=-mod=readonly 强制这一约束，任何依赖变更都必须是开发者显式动作。

方式二：devcontainer 自动搭建

这是较新增加的环境，目标是让新贡献者更快上手，适用于 etcd 3.6 及以上版本。它可以在安装了 Visual Studio Code 与 Docker 的本地系统上使用，也可以在云端 Codespaces 环境中使用。

仓库已内置 devcontainer 配置 .devcontainer/devcontainer.json，其关键内容：

{
    "image": "mcr.microsoft.com/devcontainers/go:dev-1.26-bookworm",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
        "ghcr.io/devcontainers/features/github-cli:1": {},
        "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {}
    },
    "forwardPorts": [
        2379,
        2380
    ],
    "postCreateCommand": "make build"
}

从配置可以看出：基础镜像内置了 Go 1.26 开发环境；集成了 docker-in-docker、GitHub CLI 与 kubectl/helm/minikube 特性；转发了 etcd 的客户端端口 2379 与集群端口 2380，容器内启动的 etcd 实例可被本地客户端直接访问；容器创建完成后自动执行 make build 完成首次构建验证。Dev container 是开放规范，除 GitHub Codespaces 外还可被其他支持该规范的工具使用。

实现变更：静态检查与测试

etcd 代码遵循 Golang 社区推荐的编码风格。提交变更需要满足两类质量门槛：通过静态分析、通过测试。

静态分析（make verify / make fix）

make verify 检查所有校验项是否通过，make fix 自动修复所有可修复项；两者也支持单项粒度（make verify-* / make fix-*）。从 Makefile 的实际定义看，verify 聚合了以下检查：

目标	校验内容
verify-bom	bill-of-materials.json 许可证物料清单是否与依赖一致
verify-lint	golangci-lint 静态分析（配置见 tools/.golangci.yaml）
verify-dep	各 Go 模块间依赖版本是否一致
verify-shellcheck	shell 脚本语法检查
verify-mod-tidy	go mod tidy -diff 是否干净
verify-shellws	shell 脚本是否误用 Tab 缩进（要求双空格）
verify-proto-annotations / verify-genproto	protobuf 注解与生成代码是否与 .proto 源一致
verify-yamllint	YAML 文件风格检查
verify-markdown-marker	Markdown 文件链接有效性
verify-go-versions	各模块 Go 版本一致性
verify-gomodguard	模块依赖白名单（gomodguard）
verify-go-workspace	go.work.sum 是否与 workspace 同步
verify-grpc-experimental	gRPC experimental API 使用情况

单项示例：make verify-bom 校验 bill-of-materials.json 是否最新，对应的 make fix-bom（scripts/fix/bom.sh）则负责更新该文件。

测试（make test-*）

• make test-unit：运行单元测试；
• make test-integration：运行集成测试；
• make test-e2e：运行端到端测试（依赖 build 目标先产出二进制）。

项目要求：所有变更都必须附带单元测试；所有新功能必须附带 e2e 或集成测试之一。

从 scripts/test.sh 的实现可以看到各测试层的真实参数：

• unit：对 workspace 下所有模块执行 go test -short -failfast，默认超时 3 分钟，amd64/arm64 架构自动开启 --race；
• integration：运行 tests/integration/ 与带 integration 构建标签的 tests/common/ 用例，并发度 -p=2，默认超时 15 分钟；
• e2e：运行 tests/e2e/ 下测试，这些测试直接驱动 make build 产出的预构建二进制（因此 --race、-cover 等编译参数对 e2e 不生效），默认超时 30 分钟。

scripts/test.sh 还支持细粒度运行，例如 PASSES=unit PKG=./wal TESTCASE=TestNew TIMEOUT=1m ./scripts/test.sh 只跑指定包的指定用例前缀，这对本地快速迭代很有用。

提交变更：commit message 规范

etcd 对提交信息采用如下约定：

• 第一行：以受影响的包名（例如 etcdserver、etcdctl）加冒号开头，随后描述变更的“做了什么（what）”；
• 正文（可选）：作者可补充变更的“为什么（why）”；
• 最后一行：Signed-off-by: firstname lastname <[e-mail]>，也可通过 git commit --signoff 自动生成。

仓库文档中给出的示例：

etcdserver: add grpc interceptor to log info on incoming requests

To improve debuggability of etcd v3. Added a grpc interceptor to log
info on incoming requests to etcd server. The log output includes
remote client info, request content (with value field redacted), request
handling latency, response size, etc. Uses zap logger if available,
otherwise uses capnslog.

Signed-off-by: FirstName LastName <[e-mail]>

创建 Pull Request

• 尚在开发中的 PR 可以转为 Draft（点击评审者列表下方的 Convert to draft），避免过早进入评审；
• 多个小 PR 优于单个大 PR，经验阈值是超过约 500 行代码就应考虑拆分；
• 每个 PR 必须有对应 issue。如果不存在就先创建；PR 合入且（如需）已回合到之前的稳定版本后关闭该 issue。若一个 issue 关联了多个 PR，在所有 PR 合入并回合完毕之前不要关闭 issue。

Pull Request 审查与合入

• 请求评审前，确保 GitHub 与 Prow 的所有检查通过。对于外部贡献者的 PR，可能带有 needs-ok-to-test 标签，需要 etcd-io 组织成员评论 /ok-to-test 后才会触发全部检查；
• 若 PR 中有与你的改动无关的测试因 flaky 而失败，应为其开一个 deflake issue，并请求维护者重跑测试；
• 全部检查通过后，可邀请参与过原讨论的成员或 OWNERS 中列出的维护者进行评审。根据 PR 复杂度，合入前通常需要 1 到 2 位维护者批准。

维护者角色（approver）的完整名单定义在根目录 OWNERS 与 OWNERS_ALIASES 中（如 sig-etcd-chairs、sig-etcd-tech-leads 等 alias 组），角色晋升的具体要求参见 Documentation/contributor-guide/community-membership.md。