community/contributors/guide/contributor-cheatsheet/README-zh.md

Kubernetes 贡献者备忘单

这是一份参与 Kubernetes 协作时的常用资源清单，包含 Kubernetes 项目中常用的提示、技巧和最佳实践。这个「长话短说」或快速参考包含一些有用的信息，能让您有更好的 GitHub 贡献体验。

目录

• 有用的资源
  • 入门
  • SIG 以及其它小组
  • 社区
  • 工作流程
  • 测试
  • 重要的 Email 地址
  • 其它有用的链接
• 在 GitHub 上有效沟通
  • 如何友好对待彼此
    • 良好和不良沟通的例子
• 提交贡献
  • 签署 CLA
  • 提交和回应 Issue
    • 提交 Issue
    • 回应 Issue
  • 提交 Pull Request
    • 创建 Pull Request
    • PR 描述示例
    • PR 故障排除
  • 标签
• 在本地工作
  • 分支策略
    • 添加上游
    • 让您的工作保持同步
    • 压缩提交

---

有用的资源

入门

• 贡献者指南 - 如何开始参与 Kubernetes 协作的指南
• 开发者指南 - 直接向 Kubernetes 项目贡献代码的指南
• 安全和披露信息 - 报告漏洞的指南和安全发布过程

SIG 以及其它小组

• 主要小组列表

社区

• 日历 - 查看所有的 Kubernetes 社区事件（SIG 或 WG 会议、活动等）
• kubernetes-dev - Kubernetes 开发邮件列表
• Kubernetes 论坛 - Kubernetes 官方论坛
• Slack 频道 - Kubernetes 官方 Slack
• Stack Overflow - Kubernetes 用户提问的地方
• YouTube 频道 - Kubernetes 社区的官方频道

工作流程

• Gubernator 仪表盘 - 收到和发出的 PR，您需要关注它们
• Prow - Kubernetes CI/CD 系统
• Tide - 管理合并和测试的 Prow 插件 Tide 仪表盘
• Bot 命令 - 用来和 Kubernetes 机器人互动的命令（例如 /cc、/lgtm 和 /retest）
• GitHub 标签 - Kubernetes 整个项目中使用的标签列表
• Kubernetes 代码搜索, 由 @dims 维护

测试

• Prow - Kubernetes CI/CD 系统
• Test Grid - 查看过往的测试以及相关信息
• Triage 仪表盘 - 把相似的失败聚合在一起以便排除故障
• Velodrome - 追踪任务和测试健康度的仪表盘

重要的 Email 地址

• community@kubernetes.io - 关于社区的问题，给社区小组（贡献者体验 SIG）的某人写邮件
• conduct@kubernetes.io - 联系行为守则委员会，私密邮件列表
• steering@kubernetes.io - 给指导委员会写邮件，地址公开，存档公开
• steering-private@kubernetes.io - 如果有敏感问题，给指导委员会的私密地址写邮件
• social@cncf.io - 联系 CNCF 的社交团队；博客、推特以及其它社交平台

其它有用的链接

• 开发者统计 - 查看所有 CNCF 项目的开发者统计

---

在 GitHub 上有效沟通

如何友好对待彼此

第一步，您需要熟悉行为守则。

良好和不良沟通的例子

当提交 issue 或寻求帮助时，请礼貌地提出您的请求：

🙂 「当我做 Y 事时，X 编译不通过，你们有什么建议吗？」

😞 「X 不起作用！请修好它！」

关闭 PR 时，请清楚和友好地解释为什么它不符合合并的要求：

🙂 「这个功能不能支持 X 使用场景，所以我将关闭这个 PR。在它提议的形式下，用工具 Y 实现会比较好。感谢您的工作。」

😞 「为什么这不符合 API 惯例？这应该在其他地方完成！」

---

提交贡献

签署 CLA

在您提交贡献之前，您必须签署贡献者许可证协议（CLA）。只有 您或者您的公司签署了 CLA，Kubernetes 项目才能接受您的贡献。

如果您在签署 CLA 时遇到任何问题，请参考 CLA 故障排除指南。

提交和回应 Issue

GitHub Issue 是追踪 bug 报告、改善请求，或者报告例如失败测试的其它问题的主要途径。它们不应该用来发布用户支持请求。对于那些问题，请查看故障排除指南，在Stack Overflow 报告，或者在 Kubernetes 论坛 跟进。

参考：

• 标签
• Prow 命令

提交 Issue

• 尽量使用 issue 模版。使用正确的模版将有助于其它贡献者回应您的 issue。
  • 遵循任何在 issue 模版中描述的指示。
• 尽量详细描述您提交的 issue。
• 使用合适的标签。如果您不确定，k8s-ci-robot 机器人（Kubernetes CI 机器人）将会回复您的 issue 并为其添加需要的标签，让分派更高效。
• 在使用 /assign @<username> 或 /cc @<username> 时注意选择。想要您的 issue 得到高效处理，分配更多的人不如使用正确的标签。

回应 Issue

• 在处理 issue 时，添加评论以便让其他人知道，避免重复的工作。
• 如果之后您解决了什么问题，在关闭前该 issue 前，先评论以便让其他人知道。
• 添加其它 PR 或 issue 的引用（或者任何可能的资料），例如 「ref: #1234」。这对于联系其它地方处理过的相关工作很有帮助。

提交 Pull Request

Pull requests（PR）是提交代码、文档或其它形式的工作的主要途径，这些工作都保存在 git 仓库中。

参考：

• 标签
• Prow 命令
• Pull request 处理
• GitHub 工作流程

创建 Pull Request

• 尽量遵循 pull request 模版的指示。这样对于回应您 PR 的人会有帮助。
• 如果是琐碎问题修复，例如失效链接、错别字或语法错误，请检查整个文档查找其它可能的错误。不要为了修复同一文档的小问题提交多个 PR。
• 关联任何与您 PR 有关的或者能被解决的 issue。
• 避免在一个提交中引入大量修改。相反地，将您的 PR 分解为多个合理的小提交。这样可以让评审您的 PR 变得更容易。
• 如果您觉得有什么需要更多解释，评论回复您的 PR。
• 有选择地使用 /assign @<username> 命令，分配过多的评审者并不能让评审过程加快。
• 如果您的 PR 是 「正在进行中的工作」，在标题前添加 [WIP] 或者使用 /hold 命令。这样可以防止该 PR 在 [WIP] 或 hold 被撤销前被合并。
• 如果您的 PR 没有得到评审，不要关闭后用同样的修改创建新 PR。在评论中使用 @<github username> 通知您的评审者。

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

这个 PR 里包含了：

• 第 1 行 - 提及其它有关的 issue 或 PR（#3064 #3097）。
• 第 2 行 - 对该 PR 做了什么事情的一个简短的描述。
• 第 4 行 - 使用 /sig contributor-experience 命令分配 SIG。
• 第 5 行 - 使用 /cc 命令指定可能对该 issue 或 PR 感兴趣的评审者。
• 第 6 行 - /kind cleanup 命令将该 issue 或 PR 添加了一个标签将它归类为清理代码、流程或者技术债务。
• 第 7 行 - /area developer-guide 命令将该 issue 或 PR 归类为与开发者指南有关。
• 第 8 行 - /assign 命令为该 PR 分配了一名批准者。k8s-ci-robot 会从 OWNERS 文件中的所有者列表中选择，推荐一名批准者。在评审结束后，他（她）将会使用 /approve 为该 PR 添加标签。

PR 故障排除

在您的 PR 提交后，一系列测试将由 Kubernetes CI 平台 Prow 运行。如果任何测试失败，k8s-ci-robot 将会回复该 PR，附上失败测试及其 log 的链接。

向您的 PR push 新的提交将会自动触发测试重新运行。

Kubernetes CI 平台偶尔会出现问题。即便您的贡献通过了所有本地测试，也会因为其它各种原因发生问题。您可以使用 /retest 命令触发重新运行测试。

关于特定测试的故障排除，请查看测试指南。

标签

Kubernetes 使用标签来分类和分派 issue 和 Pull Request。使用正确的标签将会帮助您的 issue 或 PR 得到更高效的分派。

参考：

• 标签
• Prow 命令

常用标签：

• /sig <sig name> 分配一个 SIG 来管理该 issue 或 PR
• /area <area name> 关联该 issue 或 PR 到某一个 area
• /kind <category> 给该 issue 或 PR 分类

---

在本地工作

在提交 pull request 之前，您将需要在本地完成一些工作。如果您是 git 新手，可以从 Atlassian git 教程开始学习。或者，您也可以选择斯坦福包含多语言的 Git 魔法教程。

参考：

• Atlassian git 教程
• Git 魔法
• GitHub 工作流程
• 本地测试
• 开发者指南

分支策略

Kubernetes 项目使用 GitHub 标准的 「Fork 然后 Pull」 的工作流程。在 git 术语中，您个人的 fork 被称为 「origin」，实际的项目 git 仓库被称为 「upstream」。为了保证您的个人分支（origin）与项目（upstream）保持更新，必须要在您的本地工作副本中进行设置。

添加上游

添加一个远程分支 upstream，并将它设置中的 push 选项关闭。

# 用上游仓库的 URL 替换 <upstream git repo>
# 例如：
#  https://github.com/kubernetes/kubernetes.git
#  git@github.com/kubernetes/kubernetes.git

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

您可以运行 git remote -v 列出设置过的远程分支来验证这一点。

让您的工作保持同步

获取 upstream 的所有变更，然后将您本地的 master 分支在它基础上 「rebase」。这样您本地的仓库与 upstream 项目就能保持同步了。

git fetch upstream
git checkout master
git rebase upstream/master

至少做完这些，您就可以创建一个新分支，来添加功能或修复问题了。

git checkout -b myfeature

压缩提交

压缩提交 的主要目的是创建一个清晰好读的 git 历史或者过往修改的 log。通常这会在 PR 修订的最后阶段进行。如果您不确定是否应该压缩提交，不妨先保留更多，然后交给其他贡献者来评审和批准您的 PR。