Kubernetes pull requests

提交 pull request 之前

本指南适用于已经提交请求的贡献者。如果您正在寻找有关设置开发人员环境和创建代码以贡献给Kubernetes的信息，请参见开发指南。

初次贡献者应前往“ 贡献者指南”开始学习。

确保您的拉取请求符合我们的最佳实践。这些措施包括遵循项目约定，发出小的请求和彻底注释。请阅读本文档末尾有关“ 快速审核的最佳做法”的更详细的部分。

运行本地验证

你可以在提交 pull request 之前进行本地验证，以预测持续集成是否通过。

运行并通过 make verify
运行并通过 make test
运行并通过 make test-integration

pull request 提交过程

合并 pull request 要求完成以下步骤，然后自动合并 pull request。

签署 CLA （先决条件）
打开 pull request
仅使适用于 kubernetes/kubernetes 仓库：如果需要，添加发行版本。
通过所有 e2e 测试
获得 reviewers 和代码的 OWNER 必须所有都 approve

测试和合并工作流程

Kubernetes 合并工作流使用标签，这些标签通过在comment提交命令实现。这些命令将触发你的 pull request 操作。不同的 Kubernetes 仓库在审批流程上可能需要不同的 label。在这里可以找到有关如何在 pull request 中使用标签的一般说明。pull request 机器人还将自动 suggest 或者 apply labels。

示例：要应用 SIG 标签，请在 comment 输入：

/sig apps

注意：对于正在处理但尚未准备好进行 review 的 pull request，请在 pull request 标签上加上 WIP 或者 [WIP] 并在 pull request 的 checklist 中跟踪所有剩余的 TODO

pull request 从提交到合并的过程如下：

1. 提出 pull request

2. @k8s-ci-robot assigns reviewers

3. 如果你不是 Kubernetes 组织的成员，那么 reviewers / Kubernetes 组织成员将检查该 pull request 是否可以安全测试。如果能够安全测试，他们将发表 /ok-to-test 到 comment。 Kubernetes 组织成员提交 pull request 不需要此步骤。现在，pull request 被认为是受信任的，并且将运行提交前测试：

i. 自动测试运行。通过此链接查看当前测试列表

ii. 如果测试失败，请将解决方案编辑推送到你的 pull request branch

iii. 如果测试是flake，则任何人都可以对受信任的 pull request 提交 /restart 去重跑错误的测试。

4. Reviewer提出建议

5. 将修改 push 到你的 pull request branch

6. 根据需要重复前两个步骤，直到 Reviewer 添加 /lgtm 标签。当 reviewer 在对应项目的 OWNERS, 并且使用 /lgtm 标签，这将被认为该项目代码已通过一个或者多个受信任的 reviewers review

7.（可选）一些 reviewers 希望你在此步骤 squash commits

8. 机器人根据建议分配 owner，该 owner 将 /approve 标签添加到 pull request comment 中。当 owner 在对应项目的 OWNERS ，并且使用 /approve 标签，这将被认为该项目代码已通过最终审核并已准备好自动 merge

可以在项目之间配置 Prow 的行为，你应该注意以下可配置行为：

如果你作为一个 /approver 在 OWNERS 文件中列出，则 /approve 操作隐式作用于你的PR。这可能会导致 /lgtm 标签触发 merge 操作。这配置行为存在于很多项目，包括 kubernetes/kubernetes 。你可以用 /approve cancel 移除隐式的 /approve。
如果有人同时被列为 reviewer 和 approver ，那么可以配置 /lgtm 使得 /lgtm 和 /approve 两个标签都会被应用。对于 kubernetes/kubernetes 和许多其他项目来说，这不是默认的行为，/lgtm 和 /approve 两个标签是区分开来的。

一旦测试通过且 reviewer 和 approver 添加 lgtm 和 approve 标签， pull request 将进入最终 merge pool。需要 merge pool 以确保自上次对你的 pull request 测试以来，其他 pull request 没有引入不兼容的更改。

Tide 将自动管理 merge pool。它使用 GitHub queries 去选择 PRs 到 “ tide pools ”, 尽可能多地批量运行（“tide comes in”），并将它们 merge （“ tide goes out ”）。

如果满足合并条件，则将 PRs 放入 merge pool。PR dashboard 显示了你的PR的状态和合并标准之间的差异，这样你就可以很容易地看到所有没有被满足的标准并解决它们。
如果测试失败，通过推送修改到你的pull request分支来解决问题。
如果失败是flake，pull request 是可信的，任何人都可以评论/重试。
如果测试通过，Tide 会自动合并拉取请求。

这是最后一步。你的pull request 已经被 merge

更多关于 Ok-To-Test

ok-to-test 标签由组织成员应用到来自外部贡献者的PR上，它标志着PR可以被测试。
对于一个贡献者来说，ok-to-test 标签意味着将为其PR运行常规的CI测试。
对于 reviewer 或成员来说，给 PR 贴上 ok-to-test 标签，意义更大：

i. 他们需要注意，PR 不能够浪费我们的CI/CD资源。

ii. 在运行 CI/CD 流程之前，这个 PR 是否值得测试还是需要做更多改变？

iii. PR 是否被用来运行恶意代码，滥用我们的资源？

一个 ok-to-test 标签可以减少工作量，并使贡献者的体验更加顺畅，因为他们可以知道是否有任何失败的测试。如果有的话，你可以修复测试，而他们也不需要等待很长时间才能得到维护者/指定者的审查。
标记为 ok-to-test 还取决于其他因素：

i. PR 的 Size：

如果PR的Size 为 /S 或 /M，只是为了修正语法错误或拼写错误，reviewer 可以不假思索地触发 CI/CD。

如果PR的Size 为 /XXL 是为了增加一个新的功能，一个新的API endpoint 或任何新的实质性功能。这需要遵循其他惯例和流程来进行修改。因此，它可能会有一个轻微的延迟，以获得ok-to-test的标签。

ii. 如果变化不大，其他没有被分配到这个 PR 的组织成员也可以标注 ok-to-test 标签

iii. 如果这个 PR 的 cncf-cla 为 no，那么最好等到 cncf-cla 签署之后再标注 ok-to-test 标签

iv. 带有 do-not-merge/hold 或 needs-rebase 标签的PR应该在 PR 被贴上 ok-to-test 标签之前做相应的修改。

v. 在没有对代码进行有意义的修改的情况下，错误创建的PR不应该被标记为ok-to-test并关闭。

标记未完成的 pull request

如果你想在你的 pull request 实施完成之前征集 reviews，你应该 hold 住你的 pull request 以保证 Tide 不会选择它并且试图将它 merge。有两种方式可以实现：

你可以添加 /hold 或者 /hold cancel 命令到comment。
你可以添加或者移除以 WIP 或者 [WIP] 为前缀的 pull request title

GitHub 机器人将会在你添加命令时添加或删除 do-not-merge/hold 标签，在编辑 pull request 标题时添加或删除 do-not-merge/work-in-progress 标签。当其中一个标签存在时，你的 pull request 将不会考虑合并。

Pull Requests and the Release Cycle

如果 pull request 已经被 review，但被保留或者未被批准，可能是由于当前处于 Release 周期。偶尔，一个 SIG 在实现可能影响其他开发工作的特定功能或者目标时，可能会冻结自己的代码。在这段时间里，你的 pull request 可能会在他们的 Release 工作完成之后仍未被 merge。

如果你觉得你的 pull request 处于这种状态，请联系相应的 SIG 或者 SIG-Release 进行说明。

Comment Commands Reference

命令文档包含了所有comment命令的参考。

自动化

Kubernetes开发者社区使用各种自动化来管理 pull request。在自动化文档中详细描述了自动化。

e2e测试如何运作

端到端测试会将状态结果发布到拉取请求中。如果一个e2e测试失败了，@k8s-ci-robot 会在 pull request 中说明测试历史和重新运行该测试的 comment 命令。例如：

测试出错，使用 /retest 命令去重跑测试

为什么我的 pull request 被关闭了？

超过 90 天的拉取请求将被关闭。对于有积极审查意见的 pull request ，或者正在等待其他依赖的 pull request，可以作为例外。已关闭的拉取请求很容易重新创建，而且关闭一个拉取请求，随后需要重新打开，几乎没有损失。我们希望对正在进行的 pull request 数量进行限制：

保持干净的项目
删除由于代码随着时间发生变动而难以重新构建的旧 pull request
鼓励代码迭代

为什么我的 pull request 没有得到 review？

有几个因素会影响你的 pull request 等待 review。

如果是 milestone 最后几周，我们会减少操作使其稳定下来。

或者，它可能与最佳实践有关。一个最常见的问题是，pull request 太大导致无法 review。比如说你修改了39个文件，有8657次插入。当 reviewer 拉取文件变动时，他们需要花费4个小时对这个 PR 进行 review，但是他们并没有这四个小时去完成。只要他们有更多的空闲时间，他们会去完成。

下一节有详细的最佳实践总结，包括如何避免过长的 pull request。

但是，如果你已经遵循了最佳实践，但你仍然没有得到任何 review，你可以通过完成以下事情来推动这个过程：

确保你的拉取请求有一个指定的 reviewer（GitHub 中的 assignee）。如果没有，请在PR的 comment 中回复，要求分配一个reviewer。这是通过机器人命令来完成的（机器人可能有这方面的建议），看起来像这样：/assign @username。
在 PR 的 comment 上Ping assignee (@用户名)，并询问他们预计何时能 review。
在 Slack 上 ping assignee。记住，一个人的GitHub用户名可能和他的Slack用户名不一样。
通过电子邮件与 assignee 联系（我们很多人都有公开的电子邮件地址）。
如果你是该组织的成员，请向你提交代码的团队（通过@team-name）发送邮件。
如果你已经解决了 review 中的所有问题，但你还没有收到回信，你应该在 comment 中用 "please take another look” (PTAL) 或类似的评论来提示 assignee，表示你已经准备好进行再一次 review。
如果你仍然没有收到回复，请在Slack上的#pr-reviews频道发布 PR 的链接，以寻找更多的 reviewer。

请继续阅读，了解更多关于如何通过遵循最佳实践来获得更快的review。

快速审核的最佳实践

本节的大部分内容并不是专门针对 Kubernetes 的，但当你在进行 PR 时，最好能记住这些最佳实践。

在如何让 Kubernetes 变得更好的问题上，你刚有了一个绝妙的想法。让我们把这个想法称为 Feature-X。Feature-X 甚至没有那么复杂。你对如何实现它有一个很好的想法。你投入进去并实现它，顺便修复了一堆东西。你提交了你的 PR —— 这真是太棒了！然后它就被搁置了。一个星期过去了，也没有人 review 它。最后，有人提出了一些意见，你把这些意见修改好，然后等待更多的评论。又过了一两个星期。这显然是非常可怕的。

让我们来谈谈最佳实践，以便你的 PR 能快速得到 review。

0.熟悉项目的惯例

Development guide
Coding conventions
API conventions
Kubectl conventions

1.该功能是否需要？提交 Kubernetes 增强提案

你确定 Feature-X 是 Kubernetes 团队想要或会接受的东西吗？它的实现是否与正在进行中的其他变化相适应？你愿意花费几天或几周的工作吗？

最好事先确认。

当你想做一个大的或其他重要的改变时，你应该遵循 Kubernetes Enhancement Proposal process。

即使是小的改动，收集对你提交的问题的反馈意见也是一个好主意，甚至可以简单地在适当的 SIG 的 Slack频道中邀请代码所有者进行讨论和反馈。这里有一个 SIG 的列表。

2.越小越好: Small Commits, Small Pull Requests

Small Commits 和 Small Pull Requests 能获得更快的 review，更有可能修正。

注意力是一种稀缺资源。如果你的 PR 需要60分钟的审核时间，那么在最后30分钟，reviewer 对细节的关注度就不如前30分钟那么敏锐了。如果需要 reviewer 连续花大量时间，可能根本 review 不过来。

分解 commits

将你的 PR 分成多个 commit，在逻辑上进行分割。

做出一系列离散的提交，是表达一个想法的演化或组成一个功能的不同想法的有力方式。力求将逻辑上不同的想法分成独立的提交。

例如，如果你发现 Feature-X 需要一些预构建来适应，就做一个只做预构建的提交。然后为Feature-X做一个新的提交。

要平衡 commit 数量，一个 25 次 commit 的 PR 审查起来还是挺麻烦的，所以需要进行判断。

分解 PR

或者，回到我们的预构建的例子。你也可以fork一个新的分支，在那里做预构建，然后为那个分支发送一个 pull request。如果你能从你的 pull request 中提取出整个想法，并将这些想法作为自己 pull request 发送，你就可以避免不断重建这一痛苦问题。

Kubernetes是一个快速移动的代码库--用你的小的 pull request 以求尽快锁定你的变化，让其合并成为别人的问题。

多个小的 PR 往往比多次 commit 要好。不要担心用 pull request 会吞没我们。我们宁可有100个清晰的、小的 pull request ，也不愿意有10个不可 review 的庞大PR。

我们希望每个 pull request 都是有用的，所以请用你最好的判断力来判断哪些是 pull request，哪些是 commit。

作为一个经验准则，如果你的 pull request 与Feature-X直接相关，而不是其他，那么它可能应该是 Feature-X pull request 的一部分。如果你能解释为什么要做看似没有操作性的工作（"这让Feature-X的改变更容易，我保证"），我们可能会同意。如果你能想象到有人能独立于Feature-X找到价值，那就以 pull request 的形式试试。(不要在提交描述中用 # 来链接 pull request，因为 GitHub 会制造很多垃圾。相反，通过你的提交所在的 pull request 来引用其他的 pull request。)

3.为Fixes 和通用的 Feature 创建不同的 PR

把与你的 feature 无关的改动放到另一个拉请求中。

通常情况下，当你在实现 Feature-X 时，你会发现错误的注释，糟糕的函数命名，糟糕的结构，薄弱的类型安全等等。

你绝对应该修复这些问题（或者至少是文件问题）— 但不要和你的 feature 放在同一个 pull request 中。否则，你的 diff 将会有太多的改动，而你的 review 将看不到变动中的关键信息。

寻找机会拉出通用的 feature。

例如，如果你发现自己接触了很多模块，想想你在包之间引入的依赖关系。你正在做的一些事情是否可以变得更通用，并从 Feature-X 包中移出？你是否需要使用一个本来不相关的包中的函数或类型？如果是这样，请推广它! 我们有地方可以存放更多的通用代码。

同样，如果 Feature-X 和上个月检查过的 Feature-W 在形式上很相似，而你又重复了 Feature-W 中的一些棘手的东西，可以考虑把核心逻辑预设出来，在 Feature-W 和 Feature-X 中同时使用。(请在自己的 commit 或 pull request 中进行。)

4.Comments Matter

在你的代码中，如果有人可能不理解你为什么要做某件事（或者你以后不记得为什么了），请评论它。许多 code-review 评论就是关于这个问题。

如果您认为有一些很明显的事情我们可以跟进，请添加一个 TODO。

阅读 GoDoc — 遵循那些评论的一般规则。

5.测试

没有什么比开始 review，却发现测试不足或没有测试更令人沮丧的了。很少有 pull request 可以触及代码而不触及测试。

如果您不知道如何测试 Feature-X，请咨询! 我们很乐意帮助你设计一些容易测试的东西，或者建议合适的测试用例。

6.压缩提交（Squashing）

你的 reviewer 终于对 Feature-X 给予反馈。

请进行修正，先不要 squash。把它们放到一个新的 commit 中，然后重新推送。这样你的 review 就可以自己查看新的 commit，这比重新开始要快得多。

为了让历史记录更易读，我们可能会要求你在最后整理你的commit，但除非有人要求，否则不要这么做：通常是在拉取请求被标记为 LGTM 的时候。

每个 commit 都应该有一个好的标题行 (<70 个字符)，并包含一个额外的描述，更详细地描述所要做的改动。

更多信息，请参阅 squash commits.

Squashing 的一般准则

Sausage => squash

当有多个 commit 时，可以进行 squash，以修复原始 commit 中的错误，处理 reviewer 的反馈等。其实我们只想看到整个 PR 的结束状态和提交信息。

Layers => don't squash

当有独立的变化分层来实现一个目标时，不要 squash。例如，写一个代码 munger 可能是一个 commit ，应用它可能是另一个 commit，添加一个预提交的检查可能是第三个提交。有人会说它们应该是单独的 PR，但是在没有看到 munger 被应用的情况下，真的没有办法 test/review munger，而且需要有一个预提交的检查来确保 munger 的输出不会立即过时。

7.Commit Message 指南

PR comment 不在 commit 历史记录中体现。commits 和它们对应的 commit message 是对你的 PR 所进行的修改做出的 “永久记录”，commit message 应该准确地描述正在做的事情和原因。

Commit messages 由两部分组成：主题（subject）和主体（body）

主题是 commit message 的第一行，通常是小改动或琐碎改动所需要的唯一部分。这些可以使用 git commit -m 或 --message 标记作为 "one liners” ，但前提是必须用简短的话完整地描述出这个 commit 是什么，尤其是为什么需要这个 commit。

commit message body 是指在不使用 -m 标志的情况下运行 git commit 时，subject 下面那部分文字，它将打开这个 commit message，以便在你喜欢的编辑器中进行编辑。填写几句说明，这将对你的 PR review 和之后项目的维护都是一种有益的时间投资。

This is the commit message subject

Any text here is the commit message body

Some text

Some more text

...

# Please enter the commit message for your changes. Lines starting

# with '#' will be ignored, and an empty message aborts the commit.

# On branch example

# Changes to be committed:

# ...

使用下面的指南来帮助制作格式良好的提交信息。这主要归功于Chris Beams、Tim Pope、Scott Chacon和Ben Straub之前的工作。

Try to keep the subject line to 50 characters or less; do not exceed 72 characters
The first word in the commit message subject should be capitalized unless it starts with a lowercase symbol or other identifier
Do not end the commit message subject with a period
Use imperative mood in your commit message subject
Add a single blank line before the commit message body
Wrap the commit message body at 72 characters
Do not use GitHub keywords or (@)mentions within your commit message
Use the commit message body to explain the whatand whyof the commit

8.KISS, YAGNI, MVP, etc.

有时我们需要互相提醒软件设计的核心原则 —— Keep It Simple, You Aren't Gonna Need It, Minimum Viable Product 等等。添加一个 feature 是 “因为我们以后可能会需要它” 是与软件设计相违背的。添加你现在需要的东西，（最好）为你以后可能需要的东西留有余地 ——但不要现在就实现它们。

9.允许推翻

有时 reviewer 会犯错误。推翻 reviewer 要求的修改是可以的。如果您有很好的理由以某种方式做某事，您绝对可以就所要求的修改的优点进行辩论。审稿人和被审稿人都应该努力以礼貌和尊重的方式讨论这些问题。

你可能会被推翻，但你也可能获胜。我们是很讲道理的人。

开源项目的另一个现象（任何人都可以对任何问题发表评论）— — 你的拉取请求得到了很多人的评论，以至于很难跟进。在这种情况下，你可以询问 reviewer（assignee）是否希望你 fork 一个新的pull request来清除所有的评论。你不一定要解决每一个喜欢评论的人提出的每一个问题，但是你应该回答合理的评论。

10.常识和礼貌

任何文档都不能代替常识和良好的品味。使用你最好的判断力，同时你要花点心思考虑如何让你的工作更容易被 review。如果你做了这些事情，你的 PR 就会被 merge，减少摩擦。

11.琐碎的编辑

每个 Pull Request 都需要被审查、检查，然后合并。

虽然自动化可以帮助解决这个问题，但每个贡献都有工程成本。因此，我们希望您不要进行琐碎的编辑和修复，而是专注于对整个文件进行审查。

如果您发现一个语法或拼写错误，很可能在该文件中还有更多的错误，您可以通过检查格式，检查断裂的链接，修复错误，然后一次性提交所有的修复到该文件中，从而真正让您的 Pull Request 更有价值。

有些问题需要考虑：

文件可以进一步改进吗？
琐碎的编辑是否能大大提高内容的质量？

Kubernetes pull requests相关推荐

在 VS Code 中轻松 review GitHub Pull Requests
相信大家在平时工作或者自己的项目中,一定都有在 GitHub 上进行 Code Review 的经历.对于韩老师来说,不论是平时工作的项目,还是自己的业余项目,代码基本都是在 GitHub 上.所以, ...
【教程】Pull Requests —— 让团队成员间的协作更轻松方便！
Pull Requests -- 让团队成员间的协作更轻松方便! Pull Requests 是方便开发者之间协作的功能.提供了一个用户友好的 Web 界面,在集成提交的变更到正式项目前可以对变更进行 ...
Github删除Commits GitHub Pull Requests（Pycharm）
Github删除Commits & GitHub Pull Requests(Pycharm) 一. 删除指定Commits之后的所有Commits 二. GitHub Pull Reques ...
Code Issues 2,637 Pull requests 0 Projects 1 Wiki Security Insights Settings 使用filter node快速找到XML f
需求是找出attribute uuid为如下high light值的xml node及其parent node的信息: 使用如下report: REPORT z_xml_filter. PARAMET ...
Cabin, 手机端的Kubernetes管理app
2019独角兽企业重金招聘Python工程师标准>>> Cabin, the mobile app for Kubernetes Cabin is a Mobile applicat ...
刚刚 Kubernetes 1.25 正式发布，所有变化都在这儿了
此版本带来了 40 项增强功能,略少于Kubernetes 1.24 中的 46 项.在这 40 项增强功能中,13 项正在升级到稳定版,10 项是对现有功能的不断改进,15 项是全新的,2 项是已弃 ...
kubernetes 部署_kubernetes应用程序部署工具概述
kubernetes 部署 Deploying applications to Kubernetes can be as simple as writing a few resource defini ...
Kubernetes 的 CI/CD 管道概述
An Overview of CI/CD Pipelines With Kubernetes Take a look at CI/CD approaches in a Kubernetes ecosy ...
Kubernetes 网络疑难杂症排查分享
本文作者来自腾讯云容器服务(TKE)团队,经常帮助用户解决各种 Kubernetes 的疑难杂症,积累了比较丰富的经验,本文分享几个比较复杂的网络方面的问题排查和解决思路,深入分析并展开相关知识,信息 ...
Kubernetes issue triage
一.为什么我们需要Issue triage Issue triage 是交由 SIG 接收和审查新的 GitHub issues 和 requests 的过程,并组织 SIG 内的成员或其他SIG 的 ...

Kubernetes pull requests

Kubernetes pull requests相关推荐

最新文章

热门文章