为 Linkerd2 贡献代码：DCO 签名、Commit 规范与 Pull Request 全流程实战指南-平芜编程栈

服务网格
云原生
可观测性

【免费下载链接】linkerd2

Ultralight, security-first service mesh for Kubernetes. Main repo for Linkerd 2.x.

项目地址：https://gitcode.com/gh_mirrors/li/linkerd2

Linkerd2 是一个面向 Kubernetes 的轻量级、安全优先的服务网格（service mesh），其主仓库采用 Go、Rust 与 React 混合开发，包含 CLI、控制平面、Rust 数据平面以及 viz、multicluster 等扩展模块。本文以仓库根目录的 CONTRIBUTING.md 为核心骨架，完整讲解从「提交 issue 提议变更」到「PR 被合并」的贡献闭环：包括每个提交必须遵守的 Developer Certificate of Origin（DCO）三种签署方式、PR 提交流程与合并条件、以及 Linkerd2 特有的 Subject/Problem/Solution/Validation 四段式 commit message 规范。读完本文，你将掌握一套可以直接照做的开源贡献操作手册，并理解这些流程在仓库治理（MAINTAINERS.md、GOVERNANCE.md）层面的来龙去脉。

贡献前了解项目

在动手之前，先明确你正在向什么项目提交代码。根据 README.md 的说明，Linkerd 是 CNCF（Cloud Native Computing Foundation）旗下的项目，主打「Ultralight、security-first」，目标是零代码改动地为 Kubernetes 应用增加安全、可观测性与可靠性能力。本仓库承载 Linkerd 2.x 系列的主体开发，主要包括：

cli：linkerd命令行工具，用于查看和驱动控制平面；
controller：控制平面核心，包括 destination（服务发现）、proxy-injector（注入 sidecar 的 mutating webhook）、identity（mTLS 证书签发）等 Go 微服务；
policy-controller：基于 Rust 的策略控制器；
viz：可观测性扩展，提供 metrics-api、tap、web 仪表盘；
multicluster：多集群扩展，提供 service-mirror 等服务；
web：React 编写的仪表盘前端。

从源码结构看，这个仓库同时承载了 Go 控制平面、Rust 数据平面相关的 API 定义与测试套件，因此贡献者通常至少需要熟悉 Go 或 Rust 之一。关于更完整的开发与构建指引，请阅读 BUILD.md；测试相关的完整说明则见 TEST.md，后文会多次引用。

遇到问题先获取帮助

贡献的第一步不是写代码，而是了解「去哪里问问题」。CONTRIBUTING.md 建议：如果对 Linkerd2 有疑问或遇到使用问题，优先在官方论坛提问，或加入社区 Slack 的 #linkerd2 频道。如果你准备提交一个修复或新功能，则应先提交一个 issue 描述你提议的变更，维护者通常会尽快响应。

这符合 Linkerd 的开放治理理念——GOVERNANCE.md 明确写道，任何人都可以通过代码、文档、博客、社区运营等方式成为贡献者，而所有贡献都必须遵循 CONTRIBUTING.md 的准则；是否合入则由维护者决定。

Developer Certificate of Origin：每个提交的法律前提

Linkerd2 采用Developer Certificate of Origin（DCO）机制来确认每位贡献者对其提交拥有合法权利，而不是像部分项目那样要求签署 Contributor License Agreement（CLA）。这意味着：你为项目做的每一个提交，都必须同意 DCO。

DCO 的完整文本位于仓库根目录的 DCO 文件，对应 Linux Foundation 发布的 Developer Certificate of Origin 1.1 版本。其核心内容可以概括为四条规定：

(a)贡献全部或部分由你本人创作，你拥有提交它的权利；
(b)贡献基于先前的工作，且据你所知，该先前工作在合适的开源许可下，你有权在相同许可下提交修改版；
(c)贡献由其他已认证 (a)、(b) 或 (c) 的人直接提供给你，且你未作修改；
(d)你理解并同意该项目与贡献是公开的，提交记录（包括你提交的所有个人信息）将被无限期保留，并可能按项目或所涉开源许可的规定进行再分发。

也就是说，DCO 用一段简洁的自我声明替代了繁琐的协议签署流程，但要求贡献者对自己的署名真实性负责。CONTRIBUTING.md 为满足 DCO 提供了三种方式。

方式一：在 commit message 中签名（推荐）

最简单、最常见的方式，是在 git commit message 末尾追加一行：

Signed-off-by: Jane Smith <jane.smith@example.com>

大多数情况下，你无需手动敲这一行——使用git commit的-s标志即可自动添加：

git commit -s -m "Your commit message"

务必注意硬性约束：签名必须使用你的真实姓名和一个可联系的邮箱地址，项目明确不接受笔名（pseudonyms）或匿名贡献。这保证了 (a) 条款中「我有权提交」的声明是可追溯的。

方式二：在 PR 评论中发表公开声明

如果你已经完成了提交、又不希望用 git 历史改写（shenanigans）去追溯补签名，还有另一条路：在对应 PR 的评论里留下这样一句话：

"I agree to the DCO for all the commits in this PR."

CONTRIBUTING.md 特别说明：这种方式同样要求你的提交是在真实姓名和可联系邮箱下完成的。采用该方式时，DCO 机器人依然会报错，但维护者在合并时会手动覆盖（override）DCO 机器人的检查结果。

方式三：非常简单修改豁免

并非所有变更都需要签名。对于琐碎改动——例如拼写修正、向 ADOPTERS.md 添加条目、单词语级的小修改——不需要 DCO 签名。维护者可以自行决定覆盖 DCO 机器人对这些变更的检查。

这一豁免机制降低了社区参与的门槛，让「修一个错别字」这类微小贡献不必走完整的声明流程。

提交 Pull Request 的标准流程

CONTRIBUTING.md 给出了提交 PR 的五个标准步骤，这是把改动送进main分支的必经之路：

先提交 issue：描述你提议的变更，让社区知道你想做什么；
等待响应：维护者会尽快对 issue 作出回应，避免做重复或方向错误的工作；
Fork 仓库、开发并测试：在本地完成代码变更。仓库的 README.md 提供了在该仓库工作的基本信息，更详细的构建与开发指引见 BUILD.md；
向main分支提交 Pull Request，并注意两点：
- PR 描述中必须包含如何测试你的变更的说明；
- 如果改动涉及用户界面（UI），必须附上变更前后的界面截图。
等待所有配置的检查通过后合入，包括：
- 分支在 CI 中通过全部测试；
- 获得合适的维护者评审（维护者名单见 MAINTAINERS.md，评审与决策规则见 GOVERNANCE.md）。

本地开发与测试：让「包含测试说明」落到实处

第 4 步要求 PR 附带测试指引，这意味着贡献者自己要先跑通测试。仓库为此准备了完整的工具链，从 BUILD.md 与 TEST.md 可以看到典型工作流：

本地构建 CLI：用bin/build-cli-bin直接构建，或bin/go-run cli ...用仓库内脚本代替go run cli/main.go ...，后者通过go build缓存加速编辑-构建-测试循环；
运行单元测试：在仓库根目录执行go test -cover -race ./...覆盖全部 Go 代码；JavaScript 侧用bin/web setup安装依赖后执行bin/web test（基于 jest）；Shell 脚本用bin/shellcheck -x bin/*检查；
运行集成测试：test/integration目录下的端到端测试套件可通过bin/tests脚本运行，默认会用 k3d 自建 k3s 集群，也可用--skip-cluster-create在现有集群上执行；
更新 golden 文件：当 Kubernetes 模板变更导致cli/cmd/testdata/*.golden测试夹具过期时，用go test ./cli/cmd/... --update自动重新生成。

把「如何测试」写进 PR，本质上就是让评审者（以及未来的你）能够复现你的验证过程。

Commit 规范：四段式提交信息

Linkerd2 对提交方式有明确偏好：优先使用 squash 或 rebase 提交，使一个分支的所有变更在合入main时成为单次提交。所有 PR 在合并时都会被 squash，但提交前自行 rebase 能让你对最终的 commit message 有更好的控制。

Commit message 的最终格式

被合并进main的提交信息应遵循如下模板：

Subject Problem Solution Validation Fixes #[GitHub issue ID]

四个段落各有明确的写作目标，下面逐一展开。

Subject：一句话标题

Subject 是提交信息的门面，规范相当严格：

一行，不超过50 个字符；
描述做了什么（what is done），而不是结果；
使用主动语态（active voice）；
首字母与专有名词大写；
不以句号结尾——它是标题/主题；
在标题中引用对应的 GitHub issue 编号。

CONTRIBUTING.md 提供了正反两个例子，非常直观：

bad: server disconnects should cause dst client disconnects. good: Propagate disconnects from source to destination

bad: support tls servers good: Introduce support for server-side TLS (#347)

对比可见：好标题主动、简洁、交代了动作方向；差标题要么是被动描述结果、以句号收尾，要么过于模糊（"support tls servers" 看不出做了什么层面的支持）。

Problem：交代背景与动机

Problem 段解释你为什么要做这个变更——上下文是什么，你想解决什么问题。CONTRIBUTING.md 同时提醒：有些情况下并不存在一个"问题"，此时可以把这段理解为变更的动机（motivation）陈述。

好的 Problem 应该让一个对背景一无所知的评审者，也能在 30 秒内理解变更的起因。

Solution：描述你做了什么

Solution 段描述你所做的具体修改，CONTRIBUTING.md 给出了三个补充要点：

如果 PR 改变了行为，最好说明旧行为与新行为的差异，并附上 before/after 截图、示例 CLI 输出或变更后的 YAML；
描述实现中特别复杂或反直觉的部分，帮助评审者降低阅读成本；
列出需要后续 PR 完成的工作，并链接到相关 issue。

这其实是把「代码评审中最常被追问的问题」前置到提交信息里，既省去评审往返，也沉淀了设计决策。

Validation：证明你的改动是对的

Validation 段描述你为验证变更所做的测试，并给出评审者复现测试的指引。特别规定：与性能相关的改动，必须附带基准测试的前后对比数据（before- and after- benchmark results）。

对照 TEST.md 可以更具体地理解 "Validation" 的落地方式：Go 侧用go test -cover -race ./...，集成侧用bin/tests --name <test>定向运行端到端测试，模板类变更用--update重生成 golden 文件后比对。把这类信息写进 Validation 段，评审者就能按图索骥地复现。

合并的权力与治理机制

理解了 PR 流程和 commit 规范后，还需要知道「谁能合入、怎么决策」，这决定了你的 PR 会被怎样对待。仓库根目录的两个治理文档给出了答案：

MAINTAINERS.md：列出了当前维护者（maintainers）名单、directors（董事，负责非技术性领导职能，如代表项目与 CNCF 沟通）、Steering Committee（指导委员会）成员，以及 emeriti（荣誉退任维护者）名单，并注明新维护者的提名流程；
GOVERNANCE.md：定义了完整的治理结构——Contributors向所有人开放；Maintainers拥有合入代码的能力，且对任何人开放（任何人都可以成为维护者）；Directors由维护者多数票选举产生。项目决策原则上由维护者与董事达成共识，无法共识时启动投票，实行「每名维护者/董事一票」的简单多数制。

GOVERNANCE.md 还给出了成为维护者的路径：向现有维护者表达兴趣，在指导（guidance）下通过贡献 PR、做代码评审等方式证明资质（要求极度精通 Go 或 Rust、具备相关领域经验、有时间履行维护职责），合作数月后由维护者决定是否授予资格。

对你的 PR 而言，这意味着：合并不是自动的，它需要 CI 全绿 + 维护者评审通过；而维护者之所以能放心合入，靠的正是前文所述的 DCO 声明、规范化的 commit message 与可复现的 Validation 说明。

从仓库源码看贡献的实际落点

CONTRIBUTING.md 指向的 README、BUILD、TEST 等文档，最终都对应着仓库里真实存在的代码。以「贡献一个控制平面组件的修复」为例，你可以顺着如下路径定位代码：

destination 服务：controller/api/destination/server.go 及其测试 server_test.go，处理 proxy 的服务发现请求；
proxy 注入：controller/proxy-injector/webhook.go，mutating webhook 的核心逻辑；
身份与证书：controller/identity/validator.go 与 pkg/tls 目录下的 CA 实现；
CLI 命令：cli/cmd 下的install.go、inject.go、check.go等，配合cli/cmd/testdata/*.golden夹具做输出比对测试；
Rust 策略控制器：policy-controller 目录，使用 Cargo 管理、与 proxy-runtime.yml 及 Cargo.toml 相关联。

贡献者完全可以从一个具体 issue 出发，先读懂上述任一模块的入口与测试，再动手修改，最后按本文的 DCO、commit message 与 PR 规范提交——这正是 Linkerd2 社区长期运转的贡献闭环。

小结

总结为 Linkerd2 贡献代码的完整链路：

提问或提交 issue，先在社区确认方向；
每个提交都必须满足 DCO：优先用git commit -s自动追加Signed-off-by行（真实姓名 + 可联系邮箱），已提交的可用 PR 评论公开声明兜底，琐碎改动可豁免；
按标准流程提交 PR：fork → 开发并测试（参考 BUILD.md 与 TEST.md）→ 向main分支发起 PR，附带测试指引与（如涉 UI）前后截图；
写好四段式 commit message：Subject（≤50 字符、主动语态、引 issue）→Problem→Solution→Validation（含性能对比）→Fixes #issue；
等待 CI 与维护者评审，理解合并权力归于 MAINTAINERS.md 所列维护者，治理决策遵循 GOVERNANCE.md 的共识与投票机制。