ChaosBlade 开源贡献指南：从 Fork、构建到合并的完整开发者工作流

• 运维
• 云原生
• SRE
• AI Agent
• 人工智能

ChaosBlade 是阿里巴巴开源的一款简单易用、功能强大的混沌工程实验注入工具（当前仓库即为该项目的核心代码仓库）。本文以仓库根目录下的 CONTRIBUTING.md 为主线，结合仓库中的 Makefile、hack/、scripts/ 等真实实现，系统讲解外部开发者如何参与 ChaosBlade 社区：从可以贡献哪些内容、Fork 与分支开发的标准工作流，到本地编译验证、提交信息规范、Pull Request 提交流程、Code Review 原则，直至 DCO 签署要求。读完本文，你将完整掌握向 ChaosBlade 提交一份高质量、可快速通过评审的 PR 的全部技能。

你可以贡献什么：任何让项目更好的改动都欢迎

ChaosBlade 社区对贡献持开放态度，官方文档明确：任何能让项目变好的行动都被鼓励。在 GitHub 协作模式下，一切改进最终都可以通过 Pull Request（PR）落地。常见的贡献类型包括：

• 发现错别字（typo），直接修复；
• 发现 Bug，直接修复；
• 发现冗余代码，主动删除；
• 发现缺失的测试用例，动手补齐；
• 增强已有功能，不要犹豫；
• 发现代码晦涩难懂，添加注释使其清晰；
• 发现代码风格不佳，进行重构；
• 改进项目文档，多多益善；
• 发现文档有误，直接修正；
• ……

文档无法穷尽所有可能，其核心原则只有一条：社区期待来自你的任何 PR（WE ARE LOOKING FORWARD TO ANY PR FROM YOU）。这意味着哪怕只是补充一个单元测试、修正一个文档中的命令示例，都是有价值的贡献。

从仓库结构看，ChaosBlade 是一个多模块 Go 工程：根目录下的 cli/ 是blade命令行入口，exec/ 下按场景拆分为 os、docker、jvm、kubernetes、cri、cplus、cloud、middleware 等多个实验执行器，data/ 承载实验与准备模型，apis/ 定义混沌实验的 CRD 类型。贡献者可据此选择自己熟悉的领域切入。

准备工作：账号与最小环境

参与贡献前，你需要：

1. 注册一个 GitHub 账号（用于 Fork、Issue 与 PR 协作）；
2. 准备go（项目为 Go 编写，源码编译、测试与格式化都依赖 Go 工具链）；
3. 准备git（版本控制与分支协作的基础）。

此外，仓库的构建辅助脚本对 git 版本有硬性检查：Makefile 中定义了ALLOWGITVERSION=1.8.5，若本机 git 版本低于该值，构建时会弹出please update git to >= 1.8.5的告警，因此建议提前升级 git。

开发工作流：从 Fork 到 PR 的七个步骤

ChaosBlade 使用master分支作为开发分支，官方明确说明这是一个不稳定分支，所有活跃开发都在其上展开。贡献者遵循如下标准工作流：

1. Fork 到自己的账号：在 GitHub 上将官方仓库 fork 一份副本；
2. Clone fork 到本地：git clone <your-fork-url>拉取到本地仓库；
3. 新建分支并开发：在 fork 上基于master创建新分支，并在该分支上完成改动，避免直接在master上堆叠提交；
4. 保持分支同步：定期从上游master拉取最新变更并 rebase/merge，降低后期冲突概率；
5. 提交改动：确保提交信息（commit message）简洁、明确；
6. Push 到 fork：git push origin <branch>将本地提交推送到自己的 fork；
7. 创建 Pull Request：在 GitHub 上向官方仓库发起 PR。

官方要求：请确保 PR 对应一个 Issue。即提交 PR 前，应先在 Issue 中描述你发现的错别字、Bug、新功能或建议，再围绕该 Issue 发起 PR，便于维护者关联上下文。

PR 创建后，一个或多个 reviewer 会被指派到该 PR 上，由他们负责代码评审。在合并前，需要将评审反馈修复（fix review feedback）、错别字修正、合并与变基等琐碎提交 squash 成一个清晰简洁的最终提交信息。

编译与验证：Makefile 构建体系

进入克隆下来的项目根目录，执行：

make

即可针对当前平台完成编译（默认产出blade可执行文件）。在 Mac 操作系统上交叉编译 Linux 包时：

make build_linux

编译 chaosblade 镜像时：

make build_image

清理全部编译产物：

make clean

说明：build_linux、build_image是文档沿用的经典目标名。从当前 Makefile 的实现看，实际提供的目标是细化的多平台/多组件目标，详见下文，新贡献者可直接使用make help查看全部目标说明。

从源码看：当前 Makefile 的真实构建能力

当前 Makefile 已经演进为一套更完整的构建体系，贡献者了解这些目标有助于本地验证自己的改动：

• 通用构建目标：make build（仅构建当前平台的 cli，向后兼容）、make build_all（构建当前平台全组件）；
• 多平台目标：darwin_amd64、darwin_arm64、linux_amd64、linux_arm64、windows_amd64，用法为make linux_amd64 MODULES=cli,os,java，其中MODULES逗号分隔指定组件，可用MODULES=all全量构建；
• 组件清单：cli, os, cloud, middleware, java, cplus, cri, kubernetes, nsexec, upx, check_yaml；
• 镜像构建：build_linux_amd64_image、build_linux_arm64_image（均支持MODULES参数）与push_image；
• 版本管理：BLADE_VERSION优先取环境变量，否则从 Git Tag 提取（去v前缀），无 Tag 时回退默认值 1.8.0；generate_version目标调用 scripts/version.sh 生成 version/version_info.go（该文件头部标注DO NOT EDIT，由脚本自动生成，开发者不应手工修改）；sync_go_mod目标调用 scripts/sync_go_mod.sh，将 Makefile 中各执行器仓库的分支配置同步到 go.mod。

本地自测：测试与格式校验

改动代码后，推荐在提交前完成以下自检：

make test # 运行测试（带 -race 竞态检测并生成覆盖率） make format # 格式化 Go 代码（gofumpt + goimports） make verify # 校验格式化与 import 顺序 make license-check # 校验文件 License 头

其中make test实际执行go test -race -coverprofile=coverage.txt -covermode=atomic，覆盖./build/spec ./data ./version ./exec/...等核心包（见 Makefile）；make format与make verify分别委托 hack/update-gofmt.sh、hack/update-imports.sh、hack/verify-gofmt.sh、hack/verify-imports.sh 四个脚本执行——它们基于 hack/init.sh 的git_find()函数筛选仓库内（排除 vendor、third_party、testdata）的全部.go文件，用gofumpt -w与goimports -w -local github.com/chaosblade-io/chaosblade保证格式与 import 分组一致。这意味着你的 PR 提交前最好本地跑通make format && make verify，避免 CI 或 reviewer 因格式问题要求返工。

代码风格规范

提交前请仔细阅读 docs/code_styles.md，其中沉淀了 ChaosBlade 的代码风格规则。核心要点包括：

• 工具层面：项目使用gofmt、go vet辅助风格合规（实际构建流水线已升级为 gofumpt + goimports）；
• 评审注释：协作风格遵循 Go Code Review Comments 规范；
• 附加规则（RULE001~RULE011）：例如结构体字段注释间保留空行（RULE001）、接口方法显式命名形式参数（RULE002）、import 按系统包/项目包/第三方包分组排列（RULE003）、变量声明置于文件开头（RULE004）、错误构造统一用fmt.Errorf("failed to do something: %v", err)（RULE005）、优先"提前返回"减少嵌套缩进（RULE006）、日志与错误消息首字母小写（RULE007）、嵌套错误优先使用github.com/pkg/errors（RULE008）、注释以// 加空格开头且句末以.结尾（RULE009）、时刻遵循 DRY 原则（RULE010），以及欢迎提交新的风格规则（RULE011）。

这些规则可直接对照仓库中exec/、data/、cli/等包的实际写法来理解和实践。

提交规范：Commit Message 与 Commit Content

清晰的提交信息能帮助 reviewer 快速理解 PR 意图、加速评审。ChaosBlade 鼓励使用**明确的（EXPLICIT）**提交信息，并倡导以下提交类型：

同时，社区明确不鼓励这类含糊的提交信息：fix bug、update、add doc。如果你不确定如何写，可参考 Git 提交信息的经典写作指南入门。

关于提交内容（一个 commit 中包含的全部改动），两条规则需要牢记：

• 避免在单个 commit 中出现过大的改动；
• 每个 commit 都应完整、可独立评审，即单个 commit 的内容能够单独通过 CI，避免"代码混乱"。

无论提交信息还是提交内容，社区的重心始终是"便于 Code Review"。

Pull Request 流程：以 Issue 驱动、化整为零

ChaosBlade 使用 GitHub Issues 与 Pull Requests 作为协作追踪渠道。官方文档要求：

• 发现文档错别字、代码 Bug、想要新功能或提出建议时，先提交 Issue，并按 Issue 模板中的引导填写信息；
• 准备贡献时，遵循上述 开发工作流 创建新的 PR；
• 若 PR 涉及大改动（如组件重构或新增组件），必须附上详细的设计与使用文档；
• 单个 PR 不应过大：若需要大量改动，最好拆分成几个独立的 PR 分批提交。这一要求与 Commit Content 的"小而完整"原则一脉相承——便于 reviewer 逐份消化，也降低合并风险。

从仓库 docs/ 目录可以看到，ChaosBlade 为实验模型、逻辑流程、构建与版本同步等主题都维护了专门的文档（如 docs/chaos_experiment_model_CN.md、docs/logic_flow_Introduction_CN.md），大改动附设计文档时可直接参考这些既有文档的组织方式。

Code Review 原则：可读、优雅、可测

所有代码都必须由一名或多名 committer 充分评审。评审遵循三条原则：

• Readability（可读性）：重要代码应有良好注释，并遵循项目代码风格（见 docs/code_styles.md）；
• Elegance（优雅性）：新增的函数、类或组件应经过良好设计；
• Testability（可测性）：重要代码应具备充分的单元测试覆盖。

这三条原则在仓库中都有落地支撑：make test会生成覆盖率报告coverage.txt（Makefile），make verify保证风格与 import 规范，而 docs/code_styles.md 中的 RULE001~RULE011 正是"可读性"的具体化。贡献者在写实现的同时补足测试，是提高评审通过率最有效的方式。

行为准则与 DCO 签署

行为准则

ChaosBlade 社区承诺营造开放、友好的环境：无论年龄、体型、残障、族裔、性别特征、性别认同与表达、经验水平、教育背景、社会经济地位、国籍、个人外貌、种族、宗教或性取向，参与者在项目中都能获得无骚扰的体验。完整条款见仓库根目录的 CODE_OF_CONDUCT.md。

签署你的工作（Sign your work）

ChaosBlade 采用Developer Certificate of Origin（DCO，开发者来源证书 1.1）机制：每个补丁的说明末尾需要一行签名（sign-off），证明你编写了该补丁，或有权利将其作为开源补丁提交。DCO 的核心认证要点包括：

• (a) 贡献全部或部分由你创建，你有权在文件指定的开源许可下提交；
• (b) 贡献基于你已知晓的、受相应开源许可约束的既有工作，你有权在相同许可下提交（含修改）；
• (c) 贡献由其他已认证 (a)/(b)/(c) 的人直接提供给你，且你未做修改；
• (d) 你理解并同意：该贡献与项目均为公开的，包含你提交的所有个人信息在内的贡献记录将被无限期保留，并可依据所涉开源许可被再分发。

实操上，只需在每个 git 提交信息末尾添加一行（使用真实姓名，不接受化名或匿名贡献）：

Signed-off-by: Joe Smith <joe.smith@email.com>

如果你已配置好user.name与user.email，可以用git commit -s自动完成签名。

发布节奏（延伸参考）

虽然 PR 合并不是贡献的终点，但了解项目的发布流程有助于理解版本与分支约定：仓库提供了 scripts/release.sh 发布脚本，支持-b（构建发布包）、-t（创建 Git 标签）、-r（创建 Release）、-d（试运行）等选项，要求版本号遵循X.Y.Z[-prerelease][+build]语义化格式，并在 master/main 分支且工作区干净时执行。结合 docs/release_process.md 与 docs/version_sync_guide.md，可以看到 "Git Tag → 版本号 → go.mod 依赖同步 → 各执行器仓库分支对齐" 的版本管理链路，这与贡献者工作流中的"保持分支同步"一脉相承。

小结

参与 ChaosBlade 的贡献流程可以浓缩为一条主线：Fork 并基于 master 开分支 → 小步提交、写好 commit message → 本地用make build/make test/make verify自检 → 以 Issue 为背景发起小而完整的 PR → 遵循代码风格与 DCO 签署等待评审。本文介绍的命令、规则与原则均来自 CONTRIBUTING.md，并以 Makefile、docs/code_styles.md、hack/、scripts/ 等仓库资源做了源码级印证。现在，从修复一个错别字或补充一个测试开始你的第一个 ChaosBlade PR 吧。

• 运维
• 云原生
• SRE
• AI Agent
• 人工智能