Valkey 贡献指南实战：从 DCO 签署、clang-format 规范到 CI 工作流，带你完成首个合规 PR-育师

Valkey 贡献指南实战：从 DCO 签署、clang-format 规范到 CI 工作流，带你完成首个合规 PR

【免费下载链接】placeholderkvA flexible distributed key-value database that is optimized for caching and other realtime workloads.项目地址: https://gitcode.com/GitHub_Trending/pl/placeholderkv

本篇指南以仓库根目录的 CONTRIBUTING.md 为骨架，结合 GOVERNANCE.md、DEVELOPMENT_GUIDE.md、src/.clang-format 以及 .github/workflows 下的真实 CI 配置，系统讲解向 Valkey（一个面向缓存与实时工作负载的灵活分布式键值数据库）提交代码的完整路径。读完你将掌握：如何用 DCO 正确署名提交、如何用 clang-format-18 保证格式合规通过 CI、如何手动触发每日全量测试矩阵，以及项目对补丁、测试与文档的具体验收标准。

项目治理与贡献入口

Valkey 项目由技术指导委员会（Technical Steering Committee, TSC）领导，其职责划分在 GOVERNANCE.md 中明确说明：TSC 负责监督项目的技术、审批与政策事项，成员名单维护在 MAINTAINERS.md 中。理解治理结构有助于你判断自己提交的改动属于普通变更还是"重大技术决策"——后者（如核心数据结构变更、新增数据结构或 API、影响向后兼容的改动）需要通过投票批准。

开始贡献前，先根据你的诉求选择正确的入口：

有问题想咨询：在项目的 GitHub Discussions 或 Matrix 频道提问；
发现 Bug：按 bug 模板提交 issue（.github/ISSUE_TEMPLATE/bug_report.md 定义了填写结构）；
Valkey 崩溃：提交崩溃报告，模板见 .github/ISSUE_TEMPLATE/crash_report.yml，崩溃现场信息对排查至关重要；
建议新特性：提交详细的功能请求，务必写清使用场景（use cases），因为这是特性被接受的关键；
报告测试失败：使用 test-failure 模板；
发现安全漏洞：不要公开提交，按 SECURITY.md 中规定的渠道上报。

每个提交都必须通过 DCO 认证

Valkey 尊重他人知识产权，要求所有贡献以轻量级的"开发者来源证书"（Developer Certificate of Origin, DCO）进行正确署名与授权。DCO 并非法律合同，而是附加在每次提交上的一段声明。贡献者在提交信息中添加Signed-off-by语句，即表示同意 DCO 1.1 的条款：

Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as Indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

关键实践要点：

一个符合 DCO 的提交信息中会包含类似这样的一行：
```
Signed-off-by: Jane Smith <jane.smith@email.com>
```
项目要求使用可识别的真实身份（真实姓名或常用名），不接受匿名或化名贡献者；
最省事的方式是在本地 git 配置好user.name与user.email后，用git commit -s（即--signoff）自动在提交信息末尾追加Signed-off-by行；
即便是** revert 提交也必须包含 DCO**；
如果你以其他形式贡献代码（例如通过私人邮件或公开讨论组发送代码片段、补丁），同样需要确保贡献符合 DCO。

提交补丁与新特性的标准流程

CONTRIBUTING.md 给出了六步提交流程，其中第一步最值得注意：

先讨论，后编码：如果是重大特性或语义变更，不要直接开始写代码。先在 issue 中精确描述你想实现什么、为什么，以及具体使用场景，确认项目领导者认可、社区对想法有共识后再动手，否则可能白写大量代码；
按标准流程提交补丁：
- Fork Valkey 仓库；
- 创建主题分支：git checkout -b my_branch；
- 做出修改并用 DCO 提交：git commit -s；
- 推送到你的分支：git push origin my_branch；
- 发起 Pull Request；
耐心等待：项目维护者非常繁忙，issue 和 PR 有时需要等待很长时间。如果认为自己的 PR 很重要，可以尝试让更多用户参与评论、分享观点，这有助于提高优先级；
遵守开发规范：编码过程中务必参考 DEVELOPMENT_GUIDE.md，其中包含编写 Valkey 代码的各项最佳实践；
小修复可以直接开 PR；
关联 issue：在 PR 描述中写Fixes #xyz（xyz 为 issue 编号）即可将 PR 与已有 issue 关联。

代码格式化：clang-format-18 是硬性 CI 门槛

Valkey 强制使用clang-format-18统一代码格式，.github/workflows/clang-format.yml 中定义的 CI 检查会在每个 PR上运行，一旦格式不合规就会失败。工作流会在src目录下对**/*.c **/*.h **/*.cpp **/*.hpp运行 clang-format 并 diff 检查，任何差异都会以 Base64 编码的 diff 形式在 CI 日志中展示。

安装 clang-format-18

方式 A —— pip（跨平台）：

pip install clang-format==18.1.8

方式 B —— apt（Debian/Ubuntu）：

sudo apt-get install software-properties-common -y wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | gpg --dearmor | sudo tee /usr/share/keyrings/llvm-toolchain.gpg > /dev/null echo "deb [signed-by=/usr/share/keyrings/llvm-toolchain.gpg] http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-18 main" | sudo tee /etc/apt/sources.list.d/llvm.list sudo apt-get update -y sudo apt-get install clang-format-18 -y

格式化你的改动

只格式化修改过的文件：

clang-format-18 -i src/file_you_changed.c src/file_you_changed.h

一次性格式化全部源码：

clang-format-18 -i src/*.c src/*.h

务必使用版本 18：不同版本的 clang-format 可能产生不同输出，导致 CI 检查失败。格式规则配置在 src/.clang-format 中，从源码结构看，该配置基于 LLVM 风格并做了显著定制：缩进宽度 4（IndentWidth: 4）、关闭 80 列强制换行（ColumnLimit: 0）、短 if/loop 允许单行、SortIncludes: false（保持 include 原有顺序）、不允许短函数单行、文件末尾强制换行等。这意味着你不能简单套用 LLVM 默认风格，必须以clang-format-18结合仓库自带的配置文件为准。

从 DEVELOPMENT_GUIDE 看补充风格约定

DEVELOPMENT_GUIDE.md 在 clang-format 之外补充了人工约定的风格规则，提交前值得对照自查：

注释：/* ... */可用于单行与多行注释，//只能用于单行；多行注释的*需对齐，结尾*/与最后一行文字同行；
行宽：一般保持在 90 字符以内（无硬性强制）；
函数可见性：仅限本文件访问的函数应声明为static；
布尔类型：真/假值使用布尔类型；
命名约定：变量snake_case（如cached_reply、keylen），函数camelCase或namespace_camelCase（如createStringObject、IOJobQueue_isFull），宏UPPER_CASE（如MAKE_CMD），结构体camelCase。

按需手动运行每日测试工作流

项目每天通过 .github/workflows/daily.yml 自动跑全量测试矩阵，但你可以用workflow_dispatch在自己的 fork 分支上手动触发同样的每日测试：

打开你的 fork，进入Actions->Daily；
点击Run workflow；
在Branch下拉框选择包含目标工作流文件的分支；
在输入字段中设置：
- use_repo为你的 fork（例如your-user/valkey）；
- use_git_ref为你的分支名（或具体 commit SHA）；
可选参数：skipjobs、skiptests、test_args、cluster_test_args；
点击Run workflow。

注意事项：

要跑完整矩阵，将skipjobs和skiptests设为none，不要留空（否则会应用工作流输入的默认值）；
该工作流的定时触发部分限制在valkey-io/valkey主仓库，但手动workflow_dispatch对 fork 完全可用。

从 .github/workflows/daily.yml 的源码结构看，这个矩阵相当庞大，覆盖了多种构建与运行环境，手动触发时可通过skipjobs精确裁剪：

`skipjobs`取值	对应跳过的作业类型
`valgrind`	valgrind 内存检测系列作业
`sanitizer`	内存/地址消毒器作业
`tls`	TLS 加密构建与测试
`freebsd`/`macos`/`alpine`	对应操作系统/发行版作业
`32bit`	32 位构建作业
`iothreads`	IO 线程模式测试（`--io-threads`）
`ubuntu`/`arm`/`s390x`	对应架构/平台作业
`malloc`	不同内存分配器构建（`MALLOC=libc`等）
`specific`	专项测试（如 reclaim-cache 缓存回收验证）
`fortify`	`_FORTIFY_SOURCE=3`强化构建
`reply-schema`	回复 schema 校验

其中值得留意的典型作业：test-ubuntu-jemalloc除了常规./runtest、./runtest-moduleapi、./runtest-sentinel外，还会下载 Redis OSS 6.2/7.0 构建并执行向后兼容测试（--tags compatible-redis --other-server-path）；test-ubuntu-reclaim-cache用vmtouch验证 SAVE、复制、重启等场景下文件缓存不会异常膨胀；valgrind 系列作业通过--single参数按 unit/cluster/integration-type 分片执行。

提交代码时配套的测试与文档要求

根据 DEVELOPMENT_GUIDE.md，所有贡献都应包含某种形式的测试，并在需要时同步更新文档：

单元测试位于 src/unit 目录，用于测试单个结构或文件；大多数数据结构改动都应附带对应单元测试。src/unit/README.md 说明该框架基于 GoogleTest/GoogleMock，但测试代码本身应写成任何 C 开发者都能读懂的形式：不使用 STL 容器、不使用new/delete与智能指针、不使用模板与 lambda、不使用 C++ 风格强转。日常可通过make test-unit运行全部单元测试，用make test-unit UNIT_TEST_PATTERN='TEST_CLASS_NAME.*'过滤测试类，还支持accurate=1、large_memory=1、seed=<number>等测试标志；
集成测试位于 tests 目录，用于端到端功能验证；新增命令必须配套集成测试；编写集群模式测试时不要使用已废弃的tests/cluster框架，而应写在unit/cluster中；
文档：PR 需要更新文档时应打上needs-doc-pr标签，直到对应的文档 PR 打开。

结合 CONTRIBUTING.md 中"尽量减少 PR 改动行数"的提示可以推断，Valkey 作为需要频繁 backport 的项目，行数越少、冲突概率越低，因此将重构与功能变更拆分为不同 PR是项目明确推荐的实践。同时，"避免在能用启发式规则自动控制的场景下新增配置项"也是一条重要原则——项目希望开箱即用，只有工作量特征无法推断或涉及 CPU 与内存权衡时才应提供配置。

小结

提交一个合规的 Valkey PR，核心闭环可概括为：先在 issue 中确认想法并获得共识 → 创建主题分支并编码 → 用git commit -s完成 DCO 署名 → 用clang-format-18（严格 18 版本）格式化改动并通过本地 CI 预检 → 配套单元/集成测试 → 通过workflow_dispatch手动触发 Daily 工作流跑完整测试矩阵 → 提交 PR 并填写Fixes #xyz。上述每个环节都能在仓库中找到对应的配置或源码依据：DCO 文本与流程见 CONTRIBUTING.md，治理与投票见 GOVERNANCE.md，风格与测试规范见 DEVELOPMENT_GUIDE.md 与 src/unit/README.md，格式检查与测试矩阵分别由 .github/workflows/clang-format.yml 和 .github/workflows/daily.yml 落地执行。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考