企业官网建设流程全解析

Cilium 社区贡献指南：从功能提案到 Pull Request 合并的完整工作流

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium

本文基于 Cilium 仓库内的 How To Contribute 文档 展开，系统梳理社区贡献者的完整工作流：从功能提案（CFP）、Issue 生命周期管理，到开发环境准备、代码变更规范、Pull Request 提交要求、CI 触发与审查、大 PR 的拆分与 rebase 技巧，直至 DCO 签署和贡献者晋升路径。读完本文，你将掌握向 Cilium 提交一个"可被顺利合并"的 PR 所需的全部实操规范与仓库级实现依据。

贡献全流程总览

Cilium 面向社区贡献者的贡献路径可以概括为六个阶段：

1. 功能提案：重大改动前先提出 Cilium Feature Proposal（CFP）；
2. Issue 生命周期：理解 stale 机器人机制，避免 Issue 被误关；
3. 环境准备：fork 仓库、建立upstream远程、搭建 Kind 开发集群；
4. 代码变更：按规范分支、提交、跑 lint 与测试；
5. 提交 PR：满足提交检查单（commit message 格式、sign-off、release-note、标签等）；
6. 审查与合并：触发 CI、响应 CODEOWNERS 审查意见、按大 PR 规范处理反馈。

此外，Cilium 还提供了面向审查者与维护者的文档（reviewers_committers 目录），与本文面向社区贡献者的视角互为补充。

功能提案（Cilium Feature Proposal）

在着手一个较大的代码改动之前，最好的做法是先确认你的方案会被社区接受。官方推荐的流程是：

• 在上游仓库创建一个类型为Feature Request的 Issue，其中描述你的方案规划；
• 对于篇幅较长的提案，可以附一份外部协作文档的链接（如在线文档），方便评审者在线批注。GitHub 的 feature request 模板中提供了 Cilium Feature Proposal 模板的链接——做法是复制该模板、填入你的想法并设为公开可见，再把链接贴进 GitHub Issue；
• 经过初步讨论后，CFP 应当被归档到独立的design-cfps仓库，以便设计和讨论记录长期留存，供后续参考。

这条流程的价值在于：把一个可能数百行的改动，前置为一段低成本的方案讨论，避免贡献者花数周开发后才发现方向不被采纳。

Issue 生命周期与 Stale 管理

Cilium 使用自动化工具管理 Issue 生命周期。理解这些机制，可以帮助重要 Issue 保持活跃，避免被误关。

Stale 机器人的具体规则

• Issue 在 60 天无活动（无评论、无 commit 引用等任何活动）后被标记为 stale；
• stale 的 Issue 再经过 14 天（即最后一次活动后共 74 天）被关闭；
• Pull Request 在 30 天无活动后标记为 stale，再过 14 天被关闭。

防止 Issue 被标记为 stale 的四种方式

1. 指派（assign）该 Issue：有任何 assignee 的 Issue 自动豁免 stale 标记；
2. 添加豁免标签，以下标签均可豁免：

3. 保持定期活动：任何评论、commit 引用或其他活动都会重置 stale 计时器；
4. 转为讨论：对于开放性的主题，建议迁移到 GitHub Discussions。

如果 Issue 已被自动关闭

如果你认为一个被自动关闭的 Issue 仍然重要：

1. 添加评论说明它应保持开启的理由；
2. 重新打开该 Issue（如果有权限），或请维护者重新打开；
3. 考虑添加合适的标签（如pinned）或请求指派，以防止未来再次被自动关闭。

这套机制的目标是：让 Issue 追踪器聚焦于活跃工作，同时保留重要的长期 Issue 与社区贡献。

克隆与开发环境准备

仓库克隆与上游远程配置

贡献的第一步是把环境搭起来。原文档给出的步骤为：

1. 准备好 GitHub 账号；
2. 把 Cilium 仓库 fork 到你自己的用户或组织下；
3. 在 fork 中关闭 GitHub Actions——官方明确建议这样做，以避免 fork 上的 CI 通知造成不必要的失败干扰；
4. 克隆你的 fork，并把上游仓库设为upstream远程：

git clone https://github.com/${YOUR_GITHUB_USERNAME_OR_ORG}/cilium.git cd cilium git remote add upstream https://github.com/cilium/cilium.git

5. 按 Development Setup 文档设置开发环境（下文摘要其关键内容）；
6. 浏览带good-first-issue标签的 Issue 列表，寻找适合入手的任务；
7. 按"代码变更规范"开始贡献。

开发环境要点（来自 dev_setup 文档）

dev_setup.rst 给出了快速上手命令：在仓库根目录执行以下命令即可在 Kind 集群中装好 Cilium。Linux 下：

make kind make kind-image-fast make kind-install-cilium-fast

任意操作系统下：

make kind make kind-image make kind-install-cilium

其中-fast系列 target 只在 Linux 上可用：它们在本地编译 Cilium 二进制，并把二进制及 BPF 源码挂载进已运行的 Cilium 容器，显著缩短迭代周期。

安装 Cilium 的 Makefile target 会向 Cilium CLI 传递以下 Helm values 文件（仓库中均可查看）：

• contrib/testing/kind-common.yaml：普通安装与 fast 安装模式共享；
• contrib/testing/kind-values.yaml：普通安装模式使用；
• contrib/testing/kind-fast.yaml：fast 安装模式使用；
• contrib/testing/kind-custom.yaml：用户自定义 values，文件存在时生效，且被 Git 忽略（见contrib/testing/.gitignore）。

make kind还支持若干环境变量来定制集群，最常用的是：CONTROLPLANES（控制面节点数）、WORKERS（工作节点数）、CLUSTER_NAME（集群名）、IMAGE（Kind 节点镜像）、KUBEPROXY_MODE（透传给 Kind 配置），更多变量见 contrib/scripts/kind.sh。

版本依赖方面，该文档列出了 clang/llvm（≥ 18.1）、Go、ginkgo、golangci-lint、Docker、helm（≥ v3.13.0）、kind（≥ v0.7.0）、kubectl（≥ v1.26.0）、cilium-cli 等要求。装好 Go 之后，可以快速自查环境：

$ make dev-doctor

该 target 在 Makefile 中定义为运行go run ./tools/dev-doctor，对应源码位于 tools/dev-doctor。注意并非所有依赖都必需——例如只改文档就不需要 Ginkgo。

代码变更规范（Making Changes）

dev_setup.rst 的 "Making Changes" 一节定义了改动 Cilium 的标准步骤：

1. 确保 fork 的main分支是最新的：

   git fetch upstream main:main

2. 从main切出语义清晰的 PR 分支：

   git switch -c pr/changes-to-something main

3. 完成你的改动，并拆分为逻辑内聚的 commit：

   • commit message 要回答"为什么需要这个改动"，记录任何可能出人意料的地方；
   • 如果理解代码改动所需的解释是必需的，那它应该写成代码注释，而不是 commit 描述。
   • 提交 PR 前所有 commit 必须签署（git commit -s），即后文的 DCO 要求。

4. 改动必须满足：

   • 新代码被集成测试覆盖；
   • 端到端集成/运行时测试被扩展或新增；如无需新增，在 commit message 中说明已有哪个测试覆盖了新代码；
   • 后续 commit 被妥善压缩（squash）——commit 应代表逻辑代码块，而不是改动的时间线。

5. 本地检查命令：

   git diff --check # 捕获明显的空白符违规 make # 构建变更，同时运行 make lint make -C bpf checkpatch # 校验 BPF 代码风格与 commit message

   其中make触发的 lint 规则配置在 .golangci.yaml。

6. 文档类改动可以运行make render-docs在http://localhost:9081本地预览（该 target 在 Makefile 中定义为make -C Documentation live-preview，需要 Docker 运行中）。

Cilium 还提供基于官方 builder 镜像的 Dev Container 配置，供 VS Code Remote Containers 与 Codespaces 使用，首次创建后可运行contrib/scripts/devcontainer-setup.sh安装kind、kubectl、cilium-cli等常用工具。

提交 Pull Request

贡献必须以上游 GitHub 仓库的 Pull Request 形式提交：fork 仓库 → 把改动推送到 fork 的主题分支 → 向上游提交 PR。

点击提交按钮前，官方文档要求逐项确认以下检查单：

1. 写好 PR 描述

花时间描述你的改动：改动动机、实现中做的选择，对评审者理解"为什么改"和"为什么是好的解法"帮助巨大。必要时用图片或 Mermaid 图辅助说明。

仓库内置的 PR 模板 pull_request_template.md 已经把这份检查单固化下来，其中包括：测试覆盖、commit 描述与Fixes: #XXX、DCO sign-off、release-note，以及按 Cilium AI 政策披露 AI 工具使用情况（标注 AI Influence Level，如 "This PR was prepared with AIL:N. I personally checked X."）。

2. 每个 commit 必须独立可编译、可工作

这样在出现 bug 时才能对 commit 做 bisect。

3. 代码必须有测试

所有代码在可行范围内都要有单元测试和/或运行时测试覆盖；所有改动都必须通过跑现有测试套件验证过回归（参见 testing 文档中的 testsuite 相关章节）。

4. Commit message 的完整格式

每个 commit 都要有包含标题、描述、以及（如解决某个 Issue 则附Fixes: #XXX行）的完整描述。合并后对应的 GitHub Issue 会被自动关闭。标题与描述之间必须有一个空行。官方文档给出的示例：

apipanic: Log stack at debug level Previously, it was difficult to debug issues when the API panicked because only a single line like the following was printed: level=warning msg="Cilium API handler panicked" client=@ method=GET panic_message="write unix /var/run/cilium/cilium.sock->@: write: broken pipe" This patch logs the stack at this point at debug level so that it can at least be determined in developer environments. Fixes: #4191 Signed-off-by: Joe Stringer <joe@cilium.io>

5. 修复树内已存在 commit 的 bug 时

如果某个 commit 修复的是树中已存在的某个 commit 引入的 bug，必须在 commit message 中引用那个 commit，确保执行 backport 的人能取回所有必需的修复：

daemon: use endpoint RLock in HandleEndpoint Fixes: a804c7c7dd9a ("daemon: wait for endpoint to be in ready state if specified via EndpointChangeRequest") Signed-off-by: André Martins <andre@cilium.io>

格式要求：引用 commit 的Fixes:标签，必须使用 git SHA 的前 12 位 + 完整 commit 标题（如上例），且标题不换行。

6. 修改 CLI 参数必须同步命令参考文档

如果改动了本仓库中任何二进制的 CLI 参数，不更新命令参考文档（Documentation/cmdref/）的话 CI 会拒绝 PR。做法是运行postcheckmake target：

$ make postcheck $ git add Documentation/cmdref $ git commit

从源码看，Makefile 中postcheck的定义是执行SKIP_BUILD=true make -C Documentation check，即由 Documentation/Makefile 的check流程完成 cmdref 更新等校验；Documentation/check-cmdref.sh与Documentation/update-cmdref.sh是其中的具体实现脚本。

7. 所有 commit 必须签署（DCO）

即后文"Developer's Certificate of Origin"一节。git commit时加-s选项可自动添加Signed-off-by:行。

8. 记录用户可见或破坏性变更

任何用户可见或破坏性的变更，都要在 Documentation/operations/upgrade.rst 中记录。

9. 选择 Milestone（可选）

为你的 PR 选择目标 milestone（例如某个发布版本），这在 feature freeze 到正式发布之间的窗口期尤为重要。

10. release-note 标签（有权限时）

这些标签用于生成用户阅读的发布说明：

11. 撰写 release note 文本

如果 PR 描述中没有显式给出 release note，PR 标题将被用于发布说明。如需自定义，在 PR 描述中添加特殊小节。发布说明主要面向用户阅读，因此 bug、major、minor 的 release note不应包含 Cilium 内部实现细节——这些细节对用户往往没有意义。

官方文档给出的反例与正例：

```release-note Fix concurrent access in k8s watchers structures

```text ```release-note Fix panic when Cilium received an invalid Cilium Network Policy from Kubernetes

注意：这与 [.github/pull_request_template.md](https://link.gitcode.com/i/a5fc6020da6e3fd24a53a8ce93561472) 中预留的 `release-note` 代码块一致——模板明确要求在此填写 release note 文本或直接删除该小节，**不要留空**。另外，如果 release note 有多行，第一行作为高层 bullet 条目，其余行作为其子条目。 ### 12. PR 标签（有权限时） | 标签 | 何时设置 | | --- | --- | | `kind/bug` | 值得写进 release notes 的 bugfix | | `kind/enhancement` | 增强 Cilium 现有功能 | | `kind/feature` | 新功能 | | `release-blocker/X.Y` | 该 PR 应阻塞下一个 X.Y 发布 | | `needs-backport/X.Y` | PR 需要 backport 到这些稳定版本 | | `backport/X.Y` | 这是 backport PR，只能在 backport 流程中设置 | | `upgrade-impact` | 代码改动可能影响升级 | | `area/*`（可选） | PR 覆盖的代码领域 | 没有权限设置标签的贡献者，可留一条评论，核心团队会代为添加；多数评审者会主动完成这一步。 ### 13. 使用 Draft 模式 如果 PR 还在进行中，请选择 Draft 模式创建 PR（"New Pull Request" 页面描述框下方的按钮，点击箭头选择 "Create draft pull request"）。Draft PR 仍然可以跑 CI。评审就绪后，点击页面底部的 **Ready for review** 通知评审者；处理评审意见期间可以再次切回 Draft 模式，改完后再点 **Ready for review** 重新请求评审。 ## 让 PR 被合并 ### 触发 CI - 提交 PR 后，评审者之一会通过回复 `/test` 触发 CI 运行；如果你是组织成员（organization member），可以自己触发。 - **静态代码分析**由 GitHub Actions 与 Travis CI 完成，Golang linter 建议会以行内评论形式给出；其他失败任务请查看构建日志获取所需操作（例如 "Please run `go mod tidy && go mod vendor` 并提交你的改动"）。 - **CI 会运行一系列测试**：单元测试、单节点运行时测试、多节点 Kubernetes 测试。 - 如果失败了一个看起来与你的 PR 无关的测试，可能是 flaky test，按 CI 失败分诊流程处理。 ### CODEOWNERS 审查机制 提交时，GitHub 会根据仓库根目录的 [CODEOWNERS](https://link.gitcode.com/i/3f2cd52ae839b54342fc2a94f4c59f20) 文件自动请求相应代码属主的审查： 1. 响应评审者反馈； 2. 可以逐个推送 commit 响应反馈，最后在合并前 rebase 你的分支； 3. 处理完反馈后，在评审者列表中点击其名字旁边的按钮重新请求评审——这样评审者会再次收到"PR 已可复审"的通知。 仓库属主会自动调整 PR 标签以跟踪其状态。当 PR 审查通过、CI 通过后，由仓库属主执行合并；如果迟迟没有发生，可以到 Cilium Slack 的 `#development` 频道询问。 评审者提供反馈时，应遵循文档化的审查流程，见 [review_process.rst](https://link.gitcode.com/i/091959614f784f0a0c4a31135918438a)。 ## 处理大型 Pull Request 当 PR 相当大时（例如**改动超过 200 行和/或超过 6 个 commit**），应考虑是否有办法拆分成更小的、可以增量合并的 PR。评审者往往对大 PR 更谨慎——理解改动的复杂度和给出建设性意见的时间成本都很高。拆成更小的逻辑 PR 的好处： - 评审者更容易给出评论并参与讨论； - 贡献者需要处理的反馈条目更少； - 更紧的反馈循环让贡献更容易进入代码树，同时减少与其他贡献的冲突。 好的拆分候选：单个 bugfix、独立的"为后续功能铺垫"的重构。 **响应大 PR 审查的技巧**：每收到一轮反馈，就新建一个 commit 来响应（因为 GitHub 的限制使评审者无法只看到上次审查以来的新改动）。等所有评审意见处理完后，把这些 commit squash 回引入改动的 commit。做法是用 `git rebase -i upstream/main`，把新 commit 移动到引入改动的 commit 之下，并把 `pick` 改成 `fixup`。官方文档的例子中，commit `d2cb02265` 会被并入 `9c62e62d8`，commit `146829b59` 会被并入 `9400fed20`： ```text pick 9c62e62d8 docs: updating contribution guide process fixup d2cb02265 joe + paul + chris changes pick 9400fed20 docs: fixing typo fixup 146829b59 Quentin and Maciej reviews

完成后强制推送到你的分支，即可请求合并。

Developer's Certificate of Origin（DCO）

为了追踪"谁做了什么"，Cilium 引入了 sign-off 程序。sign-off 是 commit 说明末尾的一行，证明你创建了该贡献或有权以开源工作形式传递它。规则很简单：只要你可以确认以下 DCO 1.1 声明，就可以签署：

Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1 Letterman Drive Suite D4700 San Francisco, CA, 94129 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 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.

然后你在 commit message 末尾添加一行：

Signed-off-by: Random J Developer <random@developer.example.org>

如果需要对已存在的 commit 补加 sign-off，可以使用git commit --amend等方式（参考 GitHub Desktop 的 amend commit 文档）。

此外，Cilium 遵循 CNCF DCO Guidelines v1.0 中的真实姓名政策：

The DCO requires the use of a real name that can be used to identify someone in case there is an issue about a contribution they made. A real name does not require a legal name, nor a birth name, nor any name that appears on an official ID (e.g. a passport). Your real name is the name you convey to people in the community for them to use to identify you as you. The key concern is that your identification is sufficient enough to contact you if an issue were to arise in the future about your contribution. Your real name should not be an anonymous id or false name that misrepresents who you are.

Contributor Ladder：贡献者晋升阶梯

为了让贡献者在权限与职责上同步成长，Cilium 设有 contributor ladder：它定义了贡献者如何从社区贡献者成长为 committer，以及每一级的期望。社区成员通常从阶梯的低层起步，随着参与度提升逐级向上；项目中的贡献者也乐于帮助你沿着阶梯前进。该阶梯的完整定义托管在社区仓库的 CONTRIBUTOR-LADDER 文档中（在贡献者达到相应级别后，即可自行触发 CI 运行、设置 PR 标签等）。

小结

Cilium 的贡献流程在"文档规范"与"工具链强制"两方面都很严格：CI 会拒绝未更新 cmdref 的 CLI 改动（make postcheck）、lint 规则由 .golangci.yaml 固定、PR 模板 .github/pull_request_template.md 把 sign-off 与 release-note 检查单前置到提交时刻。对新贡献者而言，最务实的路径是：找一个good-first-issue→ 按git fetch upstream main:main、git switch -c pr/xxx main建立分支 → 本地跑通make、git diff --check与相关测试 → 用git commit -s签署并以Fixes: #XXX关联 Issue → 以 Draft PR 起步，在反馈循环中保持 commit 逻辑内聚。遵循这些规范，你的贡献就能以最小的摩擦进入 Cilium 主干。

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium