审查拉取请求

任何人都可以审查文档拉取请求。访问 Kubernetes 网站仓库中的拉取请求部分，查看打开的拉取请求。

审查文档拉取请求是向 Kubernetes 社区介绍自己的好方法。它可以帮助您了解代码库并与其他贡献者建立信任。

在审查之前，最好先

开始之前

在您开始审查之前

  • 阅读CNCF 行为准则，并确保您始终遵守该准则。
  • 礼貌、体贴、乐于助人。
  • 评论 PR 的积极方面以及需要改进的地方。
  • 要有同理心，并注意您的评论可能被如何解读。
  • 假设对方是善意的，并提出澄清问题。
  • 经验丰富的贡献者，请考虑与需要进行大量修改的新贡献者结对。

审查流程

通常，以英语审查拉取请求的内容和风格。图 1 概述了审查过程的步骤。每个步骤的详细信息如下。

flowchart LR subgraph fourth[开始审查] direction TB S[ ] -.- M[添加评论] --> N[审查变更] N --> O[新贡献者应该
选择评论] end subgraph third[选择 PR] direction TB T[ ] -.- J[阅读描述
和评论]--> K[在
Netlify 预览构建中预览变更] end A[审查打开的 PR 列表]--> B[按标签过滤打开的 PR
] B --> third --> fourth classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,B,J,K,M,N,O grey class S,T spacewhite class third,fourth white

图 1. 审查流程步骤。

  1. 转到https://github.com/kubernetes/website/pulls。您将看到针对 Kubernetes 网站和文档的所有打开的拉取请求的列表。

  2. 使用以下一个或所有标签过滤打开的 PR

    • cncf-cla: yes（推荐）：由尚未签署 CLA 的贡献者提交的 PR 无法合并。有关更多信息，请参阅签署 CLA。
    • language/en（推荐）：仅过滤英语 PR。
    • size/<size>：按特定大小过滤 PR。如果您是新手，请从较小的 PR 开始。

    此外，请确保 PR 未标记为正在进行中。使用work in progress标签的 PR 尚未准备好进行审查。

  3. 选择要审查的 PR 后，请通过以下方式了解变更

    • 阅读 PR 描述以了解所做的更改，并阅读任何链接的问题
    • 阅读其他审查者的任何评论
    • 单击“**已更改的文件**”选项卡以查看已更改的文件和行
    • 通过滚动到“**对话**”选项卡底部 PR 的构建检查部分，在 Netlify 预览构建中预览更改。以下是屏幕截图（这显示了 GitHub 的桌面网站；如果您在平板电脑或智能手机设备上进行审查，则 GitHub Web UI 会略有不同）
      GitHub pull request details including link to Netlify preview
      要打开预览，请单击检查列表中“**deploy/netlify**”行的“**详细信息**”链接。

  4. 转到“**已更改的文件**”选项卡以开始您的审查。

    1. 单击要评论的行旁边的+符号。
    2. 填写您对该行的任何评论，然后单击“**添加单条评论**”（如果您只有一条评论）或“**开始审查**”（如果您有多条评论）。
    3. 完成后，单击页面顶部的“**审查更改**”。在这里，您可以添加您的审查摘要（并为贡献者留下一些积极的评论！）。请始终使用“评论”

    • 完成审查时，请避免单击“**请求更改**”按钮。如果您希望在进行一些进一步的更改之前阻止合并 PR，则可以发表“/hold”评论。说明您设置阻止的原因，并选择性地指定您可以或其他审查者可以解除阻止的条件。

    • 完成审查时，请避免单击“**批准**”按钮。大多数情况下，建议发表“/approve”评论。

审查清单

审查时，请将以下内容作为起点。

语言和语法

  • 语言或语法方面是否有任何明显的错误？有没有更好的表达方式？
    • 重点关注作者正在更改的页面部分的语言和语法。除非作者明确旨在更新整个页面，否则他们没有义务修复页面上的所有问题。
    • 当 PR 更新现有页面时，您应该重点审查正在更新的页面部分。应审查更改后的内容的技术和编辑正确性。如果您在页面上发现与 PR 作者尝试解决的问题没有直接关系的错误，则应将其视为单独的问题（首先检查是否存在关于此问题的现有问题）。
    • 注意_移动_内容的拉取请求。如果作者重命名页面或合并两个页面，我们（Kubernetes SIG Docs）通常会避免要求该作者修复我们在移动内容中发现的每个语法或拼写错误。
  • 是否有任何复杂或过时的词语可以用更简单的词语代替？
  • 是否有任何正在使用的词语、术语或短语可以用非歧视性的替代词代替？
  • 单词选择及其大小写是否遵循风格指南？
  • 是否有可以更短或更简单的长句子？
  • 是否有任何长段落可以更好地用列表或表格表示？

内容

  • Kubernetes 网站上的其他地方是否存在类似的内容？
  • 内容是否过度链接到站外、单个供应商或非开源文档？

网站

  • 此 PR 是否更改或删除了页面标题、slug/别名或锚链接？如果是，此 PR 是否导致链接断开？是否有其他选择，例如在不更改 slug 的情况下更改页面标题？

  • PR 是否引入了新页面？如果是

    • 页面是否使用了正确的页面内容类型和相关的 Hugo 短代码？
    • 页面是否在部分的侧边导航中正确显示（或根本不显示）？
    • 页面是否应该出现在文档主页列表中？

  • 更改是否显示在 Netlify 预览中？请特别注意列表、代码块、表格、注释和图像。

其他

  • 注意微不足道的编辑；如果您发现您认为是微不足道的编辑的更改，请指出该策略（如果它确实是一种改进，则仍然可以接受该更改）。
  • 鼓励进行空白修复的作者在其 PR 的第一次提交中进行修复，然后在此基础上添加其他更改。这使得合并和审查都更容易。特别要注意在单个提交中发生的微不足道的更改以及大量的空白清理（如果您看到这种情况，请鼓励作者修复它）。

作为审查者，如果您发现 PR 中存在对含义不重要的小问题，例如拼写错误或空白不正确，请在您的评论前加上“nit:”。这可以让作者知道您反馈的这部分内容并不重要。

如果您正在考虑批准拉取请求，并且所有剩余的反馈都被标记为 nit，则无论如何您都可以合并 PR。在这种情况下，为剩余的 nit 开一个问题通常很有用。考虑您是否能够满足将新问题标记为良好首个问题的要求；如果可以，这些都是很好的来源。

上次修改时间：太平洋标准时间 2022 年 9 月 28 日下午 1:39：修改 PR 审查指南 (336cd5f23e)