Kubernetes 贡献者速查表（Contributor Cheatsheet）实战指南：从 CLA 签署、Issue/PR 提交流程到本地 Git 分支管理

导读

本文以 Kubernetes 社区仓库中的贡献者速查表（含其多语言版本，如 Português 版、中文版）为核心，为你系统梳理参与 Kubernetes 社区贡献时的高频资源、工作流与最佳实践。无论你是第一次提交 Issue 的新人，还是想搞懂 /lgtm、/approve、/retest 等 Prow 机器人命令含义的老手，读完本文你都将掌握：如何高效创建和回应 Issue、如何写出符合社区规范的 Pull Request 描述、如何使用 Fork-and-Pull 分支策略管理本地仓库，以及从 PR 提交到自动合并的完整链路。

速查表是什么：一份 TL;DR 式贡献参考

这份速查表定位为 Kubernetes 贡献过程中的"TL;DR 快速参考"，它不替代完整的贡献者指南与开发者指南，而是把贡献者最高频接触的资源、命令与流程浓缩在一份可快速查阅的清单里。仓库中该文件还有 Deutsch、Français、中文、日本語 等多语言版本，方便非英语母语的贡献者阅读。

有用的资源：贡献前必看的资源清单

入门

• 贡献者指南：从零开始参与 Kubernetes 项目协作的入门文档，首次贡献者应从这里起步。
• 开发者指南：面向直接向项目提交代码的贡献者，涵盖开发环境搭建与本地构建。
• 安全和披露信息：报告漏洞的方法以及安全发布流程。

SIG 与其他小组

• 小组主列表：Kubernetes 以 SIG（特别兴趣小组）、WG（工作组）和委员会组织社区工作，完整列表见 sig-list.md，其中包括各小组的公开会议安排。

社区

• 日历：查看所有 Kubernetes 社区事件（SIG/WG 会议、活动等）。
• kubernetes-dev：Kubernetes 开发邮件列表。
• Kubernetes 论坛：官方论坛。
• Slack：官方 Slack 频道，其中 #pr-reviews 频道专门用于为 PR 寻找额外评审者（详见后文）。
• Stack Overflow：向 Kubernetes 终端用户提问的地方。
• YouTube 频道：社区官方频道，收录各小组会议录像。

工作流程

• Prow：Kubernetes 的 CI/CD 系统，也是社区自动化的核心。
• Tide：Prow 插件，负责管理合并与测试，其 Tide 仪表盘可查看合并池状态。
• 机器人命令（Bot 命令）：与 Kubernetes 机器人交互的注释命令，例如 /cc（抄送评审者）、/lgtm（认可代码）、/retest（重跑失败测试）。
• GitHub 标签：整个 Kubernetes 项目使用的标签列表。
• Kubernetes 代码搜索：跨仓库代码检索工具，由社区成员维护。

测试

• Prow：运行预提交测试的 CI/CD 系统。
• Test Grid：查看历史测试记录及关联信息。
• Triage 仪表盘：将相似测试失败聚合在一起，便于集中排查。

重要的邮箱别名

邮箱	用途
[e-mail]	就社区问题联系社区团队（贡献者体验 SIG）
[e-mail]	联系行为准则委员会（私密邮件列表）
[e-mail]	联系指导委员会（公开地址，存档公开）
[e-mail]	就敏感问题私下联系指导委员会
[e-mail]	联系 CNCF 社交团队（博客、Twitter 等）

其他有用链接

• 开发者统计：查看所有 CNCF 托管项目的开发者统计信息。

在 GitHub 上有效沟通：如何友好对待彼此

在开始任何贡献之前，请先熟悉行为准则。社区协作中，沟通方式直接决定协作效率与体验。速查表给出了两组鲜明的正反示例：

提交 Issue 或寻求帮助时，请保持礼貌：

• 🙂 "X 在我做 Y 时无法编译，你有什么建议吗？"
• 😞 "X 坏了！请修复！"

关闭 PR 时，给出解释性且友好的信息：

• 🙂 "我关闭这个 PR 是因为该功能无法支持用例 X。以它目前的形式，用工具 Y 实现会更好。感谢你的工作。"
• 😞 "为什么不遵循 API 约定？这应该在别处完成！"

良好的沟通不仅体现社区价值观，也能显著提高你的 Issue 和 PR 被响应的速度。关于这一点，pull-requests.md 中的"Common Sense and Courtesy"一节强调：任何文档都无法替代常识与品味，多花一点心思让你的工作更容易被评审，PR 就能更顺畅地被合并。

提交贡献：签署 CLA

在提交任何贡献之前，你必须签署贡献者许可协议（CLA）。Kubernetes 项目只能接受已签署 CLA 的个人或公司提交的贡献。具体签署步骤见 CLA.md：

1. 创建第一个 PR 后，linux-foundation-easycla 机器人会在 PR 下回复你的 CLA 状态与签署链接。
2. 授权 EasyCLA 读取你 GitHub 账号关联的部分信息（只读）。
3. 选择贡献者类型：个人贡献者（Individual Contributor）或以雇主/组织名义的法人贡献者（Corporate Contributor）。企业贡献者需确保将企业邮箱绑定到 GitHub 账号。
4. 通过 DocuSign 完成签署。
5. 签署成功后会收到通知邮件。
6. 回到 PR 回复 /easycla 更新 CLA 状态。

若签署遇到问题，按 CLA.md 的 Troubleshooting 一节处理：可从 EasyCLA 机器人的回复中提交支持工单，或发送邮件至备用支持地址。值得注意的是，社区会为 PR 打上 cncf-cla: no 这类标签，在 PR 未通过 CLA 校验前，评审者通常会暂缓对其进行测试（详见后文 ok-to-test 部分）。

提交和回应 Issue

GitHub Issue 是追踪 bug 报告、功能增强请求、测试失败等问题的主要途径，但它不是用于用户支持请求的渠道——这类请求应转向故障排查指南中列出的支持渠道、Stack Overflow 或 Kubernetes 论坛。速查表的相关论述在 issue-triage.md 中有更完整的实现依据：当提交者误把支持请求当作 bug 提交时，社区成员会将其标记为 kind/support 并引导到正确的支持渠道。

创建 Issue

• 使用 Issue 模板：若有可用模板务必使用，正确使用模板能帮助其他贡献者更快回应，并遵循模板内的指示填写。
• 描述要详细：把问题说清楚，附上复现步骤和环境信息。
• 分配正确的标签：若你不确定该用什么标签，k8s-ci-robot（Prow 机器人）会自动在 Issue 下回复所需标签，帮助它被有效分派（triage）。
• 谨慎使用 /assign @<username> 或 /cc @<username>：给 Issue 分配正确标签比分配给更多人更有效——过度分配并不会加快处理。

回应 Issue

• 处理 Issue 前先评论，让其他人知道你在处理，避免重复劳动。
• 自己解决问题后，在关闭前先评论说明，让关注者知情。
• 引用相关的 PR 或 Issue，例如写 ref: #1234，帮助其他人把相关工作联系起来。

关于 Issue 的完整分派流程（优先级定义、SIG 归属等），可进一步阅读 issue-triage.md：它详细定义了 priority/critical-urgent、priority/important-soon、priority/backlog 等优先级标签的含义，以及通过 /help、/good-first-issue 等命令为新贡献者标记合适任务的机制。

提交 Pull Request

Pull Request 是向 git 仓库贡献代码、文档或其他形式工作的主要途径。

创建 PR 的最佳实践

• 遵循 PR 模板：按模板指示填写，能帮助回应你 PR 的人。
• 琐碎修复要合并处理：如果是失效链接、错别字、语法错误这类琐碎修复，请顺手通读整个文档检查其他潜在错误，不要为同一文档的小问题开多个 PR。
• 关联相关 Issue：在 PR 描述中引用它解决的 Issue。
• 避免单次提交过大：把 PR 拆成多个小的、逻辑独立的提交，让评审更轻松。Kubernetes 社区更欢迎"100 个小而清晰的 PR"而不是"10 个无法评审的巨石 PR"。
• 在 PR 内自行评论：在你认为需要进一步解释的地方添加注释。
• 谨慎使用 /assign @<username>：分配过多评审者并不会加快评审。
• 进行中的工作打上 [WIP] 前缀或使用 /hold：这会阻止 PR 被合并，直到 [WIP] 被移除或 hold 被解除。机器人会据此自动添加/移除 do-not-merge/work-in-progress 与 do-not-merge/hold 标签。
• PR 无人评审时不要关掉重开：在评论中用 @<github username> 提醒你的评审者。
• 若 PR 长期缺乏关注：可在 Slack 的 #pr-reviews 频道发布 PR 链接，寻找额外评审者。

关于"WIP 与 hold"机制的底层实现，pull-requests.md 明确说明：只要 do-not-merge/hold 或 do-not-merge/work-in-progress 任一标签存在，Tide 就不会考虑合并该 PR。

PR 描述示例与逐行解析

速查表给出了一个标准的 PR 描述示例：

Ref. #3064 #3097
All files owned by SIG testing were moved from `/devel` to the new folder `/devel/sig-testing`.

/sig contributor-experience
/cc @stakeholder1 @stakeholder2
/kind cleanup
/area developer-guide
/assign @approver1 @approver2 @approver3

逐行含义：

• 第 1 行 Ref. #3064 #3097：引用相关的 Issue 或 PR 编号。
• 第 2 行：简要描述本 PR 做了什么事。
• 第 4 行 /sig contributor-experience：用命令将 PR 归属到某个 SIG。
• 第 5 行 /cc @stakeholder1 @stakeholder2：指定可能对该 PR 感兴趣的评审者。
• 第 6 行 /kind cleanup：添加标签，把 Issue/PR 归类为代码、流程或技术债务清理。
• 第 7 行 /area developer-guide：把 Issue/PR 归类到特定领域（如开发者指南）。
• 第 8 行 /assign @approver1 ...：为 PR 分配批准者（approver）。k8s-ci-robot 会根据 OWNERS 文件中的所有者列表推荐批准者；评审通过后，批准者会使用 /approve 添加批准标签。

这里的 /sig、/kind、/area、/cc、/assign 都属于 Prow 的评论命令体系，完整命令参考见 Prow 的命令帮助文档。命令背后的机制在 owners.md 中有系统说明：OWNERS 文件通过 approvers（可 /approve 的成员）与 reviewers（可 /lgtm 的成员）两个列表，实现了 Kubernetes 特有的两阶段代码评审流程。

PR 故障排除

• PR 提交后，一系列测试由 Kubernetes CI 平台 Prow 执行；若有测试失败，k8s-ci-robot 会在 PR 下回复失败测试与日志链接。
• 向 PR 推送新提交会自动触发测试重跑。
• CI 平台偶尔自身出问题（即便你的贡献通过了所有本地测试也可能发生），此时可用 /retest 命令触发重新运行。
• 特定测试的排查方法见测试指南。

从实现细节看，pull-requests.md 还说明：超过 90 天未活动的 PR 会被自动关闭（有活跃评审评论或依赖其他 PR 的除外），以保持项目整洁并鼓励代码流转速度。

标签：让 Issue 与 PR 被高效分派

Kubernetes 用标签来分类和分派 Issue 与 PR，打对标签是提高处理效率的关键。常用命令式标签：

• /sig <sig 名称>：将 Issue/PR 归属到某个 SIG 名下。
• /area <area 名称>：将 Issue/PR 关联到特定领域。
• /kind <分类>：对 Issue/PR 进行分类。

标签的作用远不止分类：在合并工作流中，lgtm、approved、ok-to-test、do-not-merge/hold 等标签直接驱动 Prow/Tide 的自动化行为（详见下一节）。

在本地工作：Fork-and-Pull 分支策略

在提交 PR 之前，你需要先在本地完成开发工作。如果你不熟悉 git，可以先用 Atlassian 或斯坦福大学的 Git 教程打基础。

Kubernetes 项目使用 GitHub 标准的 Fork-and-Pull 工作流：你的个人 fork 称为 origin，项目官方仓库称为 upstream。为了让个人分支（origin）与官方项目（upstream）保持同步，必须在本地工作副本中配置好远程仓库。github-workflow.md 给出了完整流程，速查表则浓缩了其中的关键步骤。

添加上游（Adding Upstream）

# 将 <upstream git repo> 替换为上游仓库 URL
# 例如：
#  https://github.com/kubernetes/kubernetes.git
#  [e-mail]:kubernetes/kubernetes.git

git remote add upstream <upstream git repo>
git remote set-url --push upstream no_push

第二行 set-url --push upstream no_push 是安全措施：把 upstream 的 push 目标设为无效值 no_push，防止误推送到官方仓库。可用 git remote -v 验证远程配置是否正确。这一细节同样出现在 github-workflow.md 中，并在第 7 步（创建 PR）处再次强调：如果你拥有 upstream 写权限，请勿用 GitHub UI 创建 PR，以免 PR 分支建在主仓库内部而非你的 fork 中。

保持 fork 与 upstream 同步

git fetch upstream
git checkout master
git rebase upstream/master

拉取 upstream 的全部变更，并把本地 master 分支 rebase 到其上，即可让本地仓库与官方项目保持同步。这是每次新建分支开发功能或修复问题之前的底线操作。随后创建功能分支：

git checkout -b myfeature

注意：github-workflow.md 特别提醒，不要用 git pull 替代上面的 fetch + rebase，因为 git pull 执行的是 merge，会产生合并提交，让提交历史变得混乱；如需改变 git pull 行为，可配置 git config branch.autoSetupRebase always 或使用 git pull --rebase。

压缩提交（Squash）

压缩提交的核心目的是创建干净、可读的 git 历史。通常这是在 PR 评审的最后阶段进行。如果你不确定是否应该压缩，宁可先保留更多提交，把判断权交给负责评审和批准 PR 的贡献者。

压缩的交互式操作方法：

git rebase -i HEAD~3
# 在编辑器中把要合并的提交从 pick 改为 squash / fixup
git push --force-with-lease

git rebase -i HEAD~3 会打开交互式编辑器，展示最近 3 个提交；把 pick 改为 squash 即可将该提交并入前一个提交，fixup 则类似 squash 但丢弃该提交的日志信息。github-workflow.md 还给出了压缩提交时应合并的提交类型清单：评审反馈修复、错别字、合并/rebase 提交、进行中的工作等；同时建议尽量让每个提交都能独立编译并通过测试，而 merge 提交必须被移除。

不想手动 squash？ 可以在 PR 下评论 /label tide/merge-method-squash，让机器人（Tide）在合并时自动完成 squash。相比手动 squash，这种方式不会移除已应用的 lgtm 标签，也不会触发 CI 重跑。但需要注意：最终提交信息将是所有提交信息的组合，因此建议参考 pull-requests.md 中的提交信息规范（subject 控制在 50 字符以内、不超过 72 字符、使用祈使语气、subject 与 body 之间留空行等）来编写有意义的提交信息。

从 PR 到自动合并：Prow 与 Tide 的完整链路

速查表提到的 Prow、Tide 与各类命令标签，最终汇成一条自动化的合并流水线。pull-requests.md 完整描述了 PR 从提交到合并的步骤：

1. 创建 PR。
2. @k8s-ci-robot 自动分配评审者。
3. 非组织成员的 PR 需要由评审者/成员确认安全后评论 /ok-to-test，才会运行预提交测试（组织成员的 PR 默认受信任）。
4. 测试失败时，推送修复提交；若是偶发失败（flake），可在受信任的 PR 上评论 /retest。
5. 评审者提出修改意见，你推送到 PR 分支，反复迭代直至评审者添加 /lgtm 标签（lgtm 由 OWNERS 文件中的 reviewer 添加，表示代码通过评审）。
6. 按机器人建议，让 OWNERS 文件中的 approver 添加 /approve 标签（表示通过最终评审、可自动合并）。
7. 测试通过且 lgtm、approved 标签齐备后，PR 进入 Tide 合并池，Tide 会批量选择可合并的 PR 并自动完成合并。

此外，ok-to-test 标签还有一些实际考量：size/S、size/M 这样的小改动（如语法修正）更容易被快速标记为可测试；而 size/XXL 这类新增功能/API 的大改动可能需要走更多流程；带 cncf-cla: no、do-not-merge/hold 或 needs-rebase 标签的 PR 需先解决对应问题。

小结

这份贡献者速查表把 Kubernetes 社区贡献的核心链路浓缩为一张可随时查阅的参考清单：从有用的社区资源、沟通礼仪，到 CLA 签署、Issue 与 PR 的正确打开方式，再到本地 git 分支策略与提交压缩。配合仓库内的贡献者指南、GitHub 工作流、PR 流程与 OWNERS 机制等详细文档，即可构成一份完整的贡献实战手册。建议将本文收藏为速查入口，遇到不熟悉的机器人命令时查阅 Prow 命令帮助，遇到标签含义问题时查阅 GitHub 标签列表，遇到本地 git 问题时回到"分支策略"一节。

上图展示了从 GitHub 云端 fork、克隆到本地、添加上游、创建分支、同步与推送的完整 git 工作流，出自 github-workflow.md，是"本地工作/分支策略"一节的可视化补充。