开发指南

相关源文件

• .github/workflows/codeql-analysis.yml
• .github/workflows/measure-testgrid-flakiness.yaml
• .github/workflows/scorecards.yml
• .gitignore
• CONTRIBUTING.md
• DCO
• Documentation/contributor-guide/branch_management.md
• Documentation/contributor-guide/community-membership.md
• Documentation/contributor-guide/features.md
• Documentation/contributor-guide/release.md
• Documentation/contributor-guide/triage_issues.md
• Documentation/contributor-guide/triage_prs.md
• GOVERNANCE.md
• Makefile
• OWNERS
• README.md
• contrib/README.md
• contrib/systemd/etcd.service
• contrib/systemd/etcd3-multinode/README.md
• scripts/codecov_upload.sh
• scripts/fix.sh
• scripts/release_notes.tpl.txt
• scripts/test.sh
• scripts/test_lib.sh
• scripts/updatebom.sh
• tests/semaphore.test.bash
• tools/mod/doc.go
• tools/mod/libs.go
• tools/mod/tools.go

本文档为希望为etcd项目做出贡献的开发者提供了一份全面的指南。它涵盖了开发工作流程、设置开发环境、构建和测试etcd以及贡献代码。有关单个主题的特定信息，请参阅相关页面：构建与测试、贡献、发布流程和CI/CD流水线。

开发工作流程概述

以下是为etcd项目贡献的整体工作流程

来源：CONTRIBUTING.md9-14 README.md163-196

设置开发环境

etcd支持两种设置开发环境的选项

选项1：手动设置

1. 克隆仓库

2. 安装Go（请在go.mod中查看所需的最低版本）

3. 安装构建工具

   • make
   • protoc (v3.20.3)
   • yamllint
   • jq
   • xz

4. 验证安装

选项2：Devcontainer

从etcd v3.6开始，您可以使用devcontainer配置，该配置可与Visual Studio Code和Docker一起使用，或在远程Codespaces环境中工作。

来源：CONTRIBUTING.md78-130

存储库结构

etcd仓库划分为几个模块

每个模块在etcd代码库中都有特定的职责，并有严格的依赖管理，以确保低级模块不依赖于高级模块。

来源：scripts/test_lib.sh79-82 README.md

构建etcd

etcd项目使用make进行构建。主要构建目标是

构建命令实现在scripts/build.sh脚本中，并且可以使用构建标志进行自定义

来源：Makefile7-25 CONTRIBUTING.md112-114

测试框架

etcd拥有一个全面的测试框架，包含多个测试环节

运行不同类型的测试

您还可以通过设置RACE环境变量来运行带有竞态检测的测试。

来源：Makefile29-69 scripts/test.sh1-39 scripts/test.sh113-161

代码验证和静态分析

etcd使用各种工具来确保代码质量

运行验证套件

来源：Makefile76-172 scripts/test.sh350-564 CONTRIBUTING.md137-143

贡献流程

etcd的贡献流程遵循以下步骤

1. 寻找可贡献之处

• 查看标记为good first issue
• 查看标记为help wanted
• 查看flaky tests

2. 实现您的更改

请遵循Go社区建议的编码风格进行更改。确保您的更改通过静态分析和测试

3. 提交您的更改

etcd遵循提交消息约定

• 第一行：以包名开头，后跟冒号（例如，etcdserver:）
• 描述更改的内容
• 最后一行：Signed-off-by: firstname lastname <email@example.com>

4. 创建拉取请求

将您的PR提交到etcd仓库。如果您仍在进行开发，请将其转换为草稿。

5. PR评审

在请求评审之前，请确保所有检查都通过。合并前需要两名维护者批准更改。

来源：CONTRIBUTING.md5-196 README.md163-196

分支管理

etcd遵循滚动发布模式，并支持两个稳定版本

• main分支：所有新功能落地的开发分支
• 发布分支：带有release-前缀的已发布版本的稳定分支
• 补丁发布：对稳定分支的常规错误修复

来源：Documentation/contributor-guide/branch_management.md1-26

测试基础设施

etcd的测试基础设施使用各种框架来满足不同级别的测试需求

测试类型	目的	命令	超时
单元测试	测试单个包	make test-unit	3分钟
集成	测试组件交互	make test-integration	15分钟
端到端测试	测试完整的系统行为	make test-e2e	30分钟
健壮性测试	测试容错性	make test-robustness	30分钟

测试框架实现在scripts/test.sh中，该脚本负责

• 运行特定模块或包的测试
• 管理测试超时
• 生成测试覆盖率报告
• 支持并行或顺序测试执行

来源：scripts/test.sh113-172 Makefile29-69

构建系统

etcd的构建系统允许为多个平台和配置进行构建

构建过程定义在Makefile中，并通过scripts/目录下的shell脚本实现，主要是scripts/build.sh。

来源：Makefile1-25 scripts/build_lib.sh

CI/CD 流水线

etcd使用GitHub Actions和Kubernetes Prow进行持续集成

CI/CD流水线执行

• 构建验证
• 单元和集成测试
• 端到端测试
• 代码质量检查
• 安全扫描

如果在CI过程中遇到测试失败，您可以在本地运行相同的测试进行调试

来源：.github/workflows/codeql-analysis.yml1-56 .github/workflows/scorecards.yml1-56 Makefile29-69

测试易失性测试管理

etcd项目积极跟踪和解决易失性测试问题

为了帮助解决易失性测试问题

1. 查找标有 type/flake 标记的测试。
2. 尝试使用 stress 工具在本地重现问题

3. 通过 pull request 修复 flaky 测试

来源： CONTRIBUTING.md47-76 .github/workflows/measure-testgrid-flakiness.yaml1-27

发布流程

etcd 遵循语义化版本控制模型，并有明确的发布流程

发布流程由专门的发布团队管理，并遵循以下步骤：

1. 准备发布说明
2. 确保里程碑完成
3. 标记发布
4. 构建并发布二进制文件和镜像
5. 发布公告

对于补丁版本，更改会从主分支挑选到稳定分支。

来源： Documentation/contributor-guide/release.md1-132

社区互动

etcd 项目拥有活跃的社区，并定期举行会议

活动	频率	详情
社区会议	每周四上午 11:00（美国太平洋时间）	讨论项目方向和重要议题
问题分类会议	每两周一次	处理 PR 和问题的积压

参与社区

• 加入 etcd-dev 邮件列表
• 加入 #sig-etcd Slack 频道
• 参加社区会议

来源： README.md139-161 GOVERNANCE.md1-43 Documentation/contributor-guide/community-membership.md1-169

故障排除

以下是开发过程中可能遇到的一些常见问题：

问题	解决方案
测试失败	检查 flaky 测试，尝试运行 PASSES="unit" ./scripts/test.sh
构建错误	确保 Go 版本与 .go-version 匹配，检查模块依赖
Linter 失败	运行 make fix 自动修复许多问题
PR 检查未运行	请维护者在您的 PR 上评论 /ok-to-test

来源： CONTRIBUTING.md187-196 scripts/test.sh42-69