审查拉取请求

任何人都可以审查文档拉取请求。访问 拉取请求 在 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
by label] 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 描述以了解所做的更改，并阅读任何链接的 issue
    • 阅读其他审阅者的任何评论
    • 单击 **更改的文件** 选项卡以查看更改的文件和行
    • 通过滚动到 **对话** 选项卡底部的 PR 构建检查部分，在 Netlify 预览构建中预览更改。以下是一个屏幕截图（这显示了 GitHub 的桌面网站；如果您在平板电脑或智能手机设备上进行审查，则 GitHub 网页界面略有不同）
      GitHub pull request details including link to Netlify preview
      要打开预览，请单击检查列表中 **deploy/netlify** 行的 **详细信息** 链接。

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

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

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

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

审查清单

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

语言和语法

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

内容

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

网站

  • 此 PR 是否更改或删除了页面标题、slug/别名或锚链接？如果是，此 PR 是否导致链接失效？是否有其他选项，例如更改页面标题而不更改 slug？

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

    • 页面是否使用正确的 页面内容类型 和相关 Hugo Shortcodes？
    • 页面是否在该部分的侧边导航中正确显示（或根本没有显示）？
    • 页面是否应该出现在 Docs Home 列表中？

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

其他

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

作为审阅者，如果您发现 PR 中没有重大意义的小问题，例如错字或不正确的空白，请在您的评论前缀为 `nit:`。这可以让作者知道您反馈的这一部分是非关键性的。

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

上次修改于 2022 年 9 月 28 日下午 1:39 PST：修改 PR 审查指南 (336cd5f23e)