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 面向社区贡献者的贡献路径可以概括为六个阶段功能提案重大改动前先提出 Cilium Feature ProposalCFPIssue 生命周期理解 stale 机器人机制避免 Issue 被误关环境准备fork 仓库、建立upstream远程、搭建 Kind 开发集群代码变更按规范分支、提交、跑 lint 与测试提交 PR满足提交检查单commit message 格式、sign-off、release-note、标签等审查与合并触发 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 引用等任何活动后被标记为 stalestale 的 Issue 再经过 14 天即最后一次活动后共 74 天被关闭Pull Request 在 30 天无活动后标记为 stale再过 14 天被关闭。防止 Issue 被标记为 stale 的四种方式指派assign该 Issue有任何 assignee 的 Issue 自动豁免 stale 标记添加豁免标签以下标签均可豁免标签用途pinned应永久保持自动开启的 Issuesecurity安全相关 Issuegood-first-issue适合新手的入门 Issuehelp-wanted寻求社区贡献的 Issue保持定期活动任何评论、commit 引用或其他活动都会重置 stale 计时器转为讨论对于开放性的主题建议迁移到 GitHub Discussions。如果 Issue 已被自动关闭如果你认为一个被自动关闭的 Issue 仍然重要添加评论说明它应保持开启的理由重新打开该 Issue如果有权限或请维护者重新打开考虑添加合适的标签如pinned或请求指派以防止未来再次被自动关闭。这套机制的目标是让 Issue 追踪器聚焦于活跃工作同时保留重要的长期 Issue 与社区贡献。克隆与开发环境准备仓库克隆与上游远程配置贡献的第一步是把环境搭起来。原文档给出的步骤为准备好 GitHub 账号把 Cilium 仓库 fork 到你自己的用户或组织下在 fork 中关闭 GitHub Actions——官方明确建议这样做以避免 fork 上的 CI 通知造成不必要的失败干扰克隆你的 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按 Development Setup 文档设置开发环境下文摘要其关键内容浏览带good-first-issue标签的 Issue 列表寻找适合入手的任务按代码变更规范开始贡献。开发环境要点来自 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.yamlfast 安装模式使用contrib/testing/kind-custom.yaml用户自定义 values文件存在时生效且被 Git 忽略见contrib/testing/.gitignore。make kind还支持若干环境变量来定制集群最常用的是CONTROLPLANES控制面节点数、WORKERS工作节点数、CLUSTER_NAME集群名、IMAGEKind 节点镜像、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 Changesdev_setup.rst 的 Making Changes 一节定义了改动 Cilium 的标准步骤确保 fork 的main分支是最新的git fetch upstream main:main从main切出语义清晰的 PR 分支git switch -c pr/changes-to-something main完成你的改动并拆分为逻辑内聚的 commitcommit message 要回答为什么需要这个改动记录任何可能出人意料的地方如果理解代码改动所需的解释是必需的那它应该写成代码注释而不是 commit 描述。提交 PR 前所有 commit 必须签署git commit -s即后文的 DCO 要求。改动必须满足新代码被集成测试覆盖端到端集成/运行时测试被扩展或新增如无需新增在 commit message 中说明已有哪个测试覆盖了新代码后续 commit 被妥善压缩squash——commit 应代表逻辑代码块而不是改动的时间线。本地检查命令git diff --check # 捕获明显的空白符违规 make # 构建变更同时运行 make lint make -C bpf checkpatch # 校验 BPF 代码风格与 commit message其中make触发的 lint 规则配置在 .golangci.yaml。文档类改动可以运行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: levelwarning msgCilium API handler panicked client methodGET panic_messagewrite 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 joecilium.io5. 修复树内已存在 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 andrecilium.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_BUILDtrue make -C Documentation check即由 Documentation/Makefile 的check流程完成 cmdref 更新等校验Documentation/check-cmdref.sh与Documentation/update-cmdref.sh是其中的具体实现脚本。7. 所有 commit 必须签署DCO即后文Developers Certificate of Origin一节。git commit时加-s选项可自动添加Signed-off-by:行。8. 记录用户可见或破坏性变更任何用户可见或破坏性的变更都要在 Documentation/operations/upgrade.rst 中记录。9. 选择 Milestone可选为你的 PR 选择目标 milestone例如某个发布版本这在 feature freeze 到正式发布之间的窗口期尤为重要。10. release-note 标签有权限时这些标签用于生成用户阅读的发布说明标签何时设置release-note/bug非平凡的 bugfix且用户可见release-note/major重大功能新增例如 Add MongoDB supportrelease-note/minor次要功能新增例如 Add support for a Kubernetes versionrelease-note/misc用户不可见的改动如重构、未发布功能的 bugfixrelease-note/ciCI 的功能或修复11. 撰写 release note 文本如果 PR 描述中没有显式给出 release notePR 标题将被用于发布说明。如需自定义在 PR 描述中添加特殊小节。发布说明主要面向用户阅读因此 bug、major、minor 的 release note不应包含 Cilium 内部实现细节——这些细节对用户往往没有意义。官方文档给出的反例与正例release-note Fix concurrent access in k8s watchers structurestext 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 模式创建 PRNew 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 会被并入 9c62e62d8commit 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完成后强制推送到你的分支即可请求合并。Developers Certificate of OriginDCO为了追踪谁做了什么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. Developers 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 randomdeveloper.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 面向社区贡献者的贡献路径可以概括为六个阶段功能提案重大改动前先提出 Cilium Feature ProposalCFPIssue 生命周期理解 stale 机器人机制避免 Issue 被误关环境准备fork 仓库、建立upstream远程、搭建 Kind 开发集群代码变更按规范分支、提交、跑 lint 与测试提交 PR满足提交检查单commit message 格式、sign-off、release-note、标签等审查与合并触发 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 引用等任何活动后被标记为 stalestale 的 Issue 再经过 14 天即最后一次活动后共 74 天被关闭Pull Request 在 30 天无活动后标记为 stale再过 14 天被关闭。防止 Issue 被标记为 stale 的四种方式指派assign该 Issue有任何 assignee 的 Issue 自动豁免 stale 标记添加豁免标签以下标签均可豁免标签用途pinned应永久保持自动开启的 Issuesecurity安全相关 Issuegood-first-issue适合新手的入门 Issuehelp-wanted寻求社区贡献的 Issue保持定期活动任何评论、commit 引用或其他活动都会重置 stale 计时器转为讨论对于开放性的主题建议迁移到 GitHub Discussions。如果 Issue 已被自动关闭如果你认为一个被自动关闭的 Issue 仍然重要添加评论说明它应保持开启的理由重新打开该 Issue如果有权限或请维护者重新打开考虑添加合适的标签如pinned或请求指派以防止未来再次被自动关闭。这套机制的目标是让 Issue 追踪器聚焦于活跃工作同时保留重要的长期 Issue 与社区贡献。克隆与开发环境准备仓库克隆与上游远程配置贡献的第一步是把环境搭起来。原文档给出的步骤为准备好 GitHub 账号把 Cilium 仓库 fork 到你自己的用户或组织下在 fork 中关闭 GitHub Actions——官方明确建议这样做以避免 fork 上的 CI 通知造成不必要的失败干扰克隆你的 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按 Development Setup 文档设置开发环境下文摘要其关键内容浏览带good-first-issue标签的 Issue 列表寻找适合入手的任务按代码变更规范开始贡献。开发环境要点来自 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.yamlfast 安装模式使用contrib/testing/kind-custom.yaml用户自定义 values文件存在时生效且被 Git 忽略见contrib/testing/.gitignore。make kind还支持若干环境变量来定制集群最常用的是CONTROLPLANES控制面节点数、WORKERS工作节点数、CLUSTER_NAME集群名、IMAGEKind 节点镜像、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 Changesdev_setup.rst 的 Making Changes 一节定义了改动 Cilium 的标准步骤确保 fork 的main分支是最新的git fetch upstream main:main从main切出语义清晰的 PR 分支git switch -c pr/changes-to-something main完成你的改动并拆分为逻辑内聚的 commitcommit message 要回答为什么需要这个改动记录任何可能出人意料的地方如果理解代码改动所需的解释是必需的那它应该写成代码注释而不是 commit 描述。提交 PR 前所有 commit 必须签署git commit -s即后文的 DCO 要求。改动必须满足新代码被集成测试覆盖端到端集成/运行时测试被扩展或新增如无需新增在 commit message 中说明已有哪个测试覆盖了新代码后续 commit 被妥善压缩squash——commit 应代表逻辑代码块而不是改动的时间线。本地检查命令git diff --check # 捕获明显的空白符违规 make # 构建变更同时运行 make lint make -C bpf checkpatch # 校验 BPF 代码风格与 commit message其中make触发的 lint 规则配置在 .golangci.yaml。文档类改动可以运行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: levelwarning msgCilium API handler panicked client methodGET panic_messagewrite 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 joecilium.io5. 修复树内已存在 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 andrecilium.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_BUILDtrue make -C Documentation check即由 Documentation/Makefile 的check流程完成 cmdref 更新等校验Documentation/check-cmdref.sh与Documentation/update-cmdref.sh是其中的具体实现脚本。7. 所有 commit 必须签署DCO即后文Developers Certificate of Origin一节。git commit时加-s选项可自动添加Signed-off-by:行。8. 记录用户可见或破坏性变更任何用户可见或破坏性的变更都要在 Documentation/operations/upgrade.rst 中记录。9. 选择 Milestone可选为你的 PR 选择目标 milestone例如某个发布版本这在 feature freeze 到正式发布之间的窗口期尤为重要。10. release-note 标签有权限时这些标签用于生成用户阅读的发布说明标签何时设置release-note/bug非平凡的 bugfix且用户可见release-note/major重大功能新增例如 Add MongoDB supportrelease-note/minor次要功能新增例如 Add support for a Kubernetes versionrelease-note/misc用户不可见的改动如重构、未发布功能的 bugfixrelease-note/ciCI 的功能或修复11. 撰写 release note 文本如果 PR 描述中没有显式给出 release notePR 标题将被用于发布说明。如需自定义在 PR 描述中添加特殊小节。发布说明主要面向用户阅读因此 bug、major、minor 的 release note不应包含 Cilium 内部实现细节——这些细节对用户往往没有意义。官方文档给出的反例与正例release-note Fix concurrent access in k8s watchers structurestext 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 模式创建 PRNew 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 会被并入 9c62e62d8commit 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完成后强制推送到你的分支即可请求合并。Developers Certificate of OriginDCO为了追踪谁做了什么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. Developers 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 randomdeveloper.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
