审查拉取请求

任何人都可以审查文档拉取请求。请访问 Kubernetes 网站存储库中的 拉取请求 部分，查看未处理的拉取请求。

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

在审查之前，最好先

• 阅读内容指南和样式指南，以便你可以留下有见地的评论。
• 了解 Kubernetes 文档社区中不同的角色和职责。

开始之前

在开始审查之前

• 阅读CNCF 行为准则并确保你始终遵守它。
• 保持礼貌、体贴和乐于助人。
• 对 PR 的积极方面和变更发表评论。
• 感同身受，并注意你的审查可能会如何被接受。
• 假设有良好的意图，并提出澄清问题。
• 经验丰富的贡献者，可以考虑与需要进行大量更改的新贡献者配对。

审查流程

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

图 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 描述以了解所做的更改，并阅读任何链接的问题
   • 阅读其他审查者的任何评论
   • 单击“Files changed”选项卡以查看已更改的文件和行
   • 通过滚动到“Conversation”选项卡底部的 PR 构建检查部分，在 Netlify 预览构建中预览更改。这是屏幕截图（显示 GitHub 的桌面站点；如果你在平板电脑或智能手机设备上进行审查，则 GitHub Web UI 略有不同）

     

     要打开预览，请单击检查列表中的“deploy/netlify”行的“Details”链接。

4. 转到“Files changed”选项卡以开始审查。

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

   • 完成审查时，请避免单击“请求更改”按钮。如果你想阻止在进行一些进一步更改之前合并 PR，你可以留下“/hold”评论。说明你为何设置保留，并可以选择指定由你或其他审查者取消保留的条件。

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

审查清单

在审查时，请使用以下内容作为起点。

语言和语法

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

内容

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

网站

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

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

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

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

博客

• 欢迎通过 Google 文档或 HackMD 对博客文章提供早期反馈。请尽早从#sig-docs-blog Slack 频道请求输入。

• 在审查博客 PR 之前，请熟悉提交博客文章和案例研究。

• 我们愿意镜像任何已发布到https://kubernetes.dev/blog/（贡献者博客）的博客文章，前提是

• 镜像文章的发布日期与原始文章的发布日期相同（它应该具有相同的发布时间，但在特殊情况下，你也可以将时间戳设置为最多晚 12 小时）

  • 对于到达的 PR，原始文章已合并到https://kubernetes.dev/，在原始文章和镜像文章发布的时间之间，主博客上没有（也不会有）任何文章发布。这是因为我们不希望在人们的订阅源（例如 RSS）中添加文章，除非在订阅源的末尾。
  • 原始文章不违反任何强烈推荐的审查指南或社区规范。
  • 你应该为镜像文章设置规范 URL，指向原始文章的 URL（你可以使用预览来预测 URL 并在实际发布之前填写此内容）。为此，请使用前言中的 canonicalUrl 字段。

• 请考虑目标受众以及博客文章是否适合 kubernetes.io。例如，如果目标受众仅为 Kubernetes 贡献者，则 kubernetes.dev 可能更合适；如果博客文章是关于通用平台工程，那么它可能更适合在其他站点上发布。

  此考虑也适用于镜像文章；尽管我们愿意考虑所有有效的贡献者文章进行镜像（如果已打开 PR），但我们不会镜像所有文章。

• 仅当 Kubernetes 项目乐于承诺无限期维护博客文章时，我们才会将其标记为已维护（在 front matter 中使用 evergreen: true）。一些博客文章绝对值得这样做，并且我们始终将发布公告标记为 evergreen。如果您不确定如何就此点进行审查，请与其他贡献者核实。

• 内容指南 无条件地适用于博客文章和添加它们的 PR。请记住，指南中的某些限制声明它们仅与文档相关；这些限制不适用于博客文章。

• 样式指南 大部分也适用于博客 PR，但我们做出一些例外情况。

  • 在具有多位作者的博客文章中，或在文章导言中明确指出作者代表特定群体进行写作的情况下，可以使用“我们”。
  • 我们避免使用 Kubernetes 短代码来表示标注（例如 {{< caution >}}）
  • 关于未来的声明是可以接受的，尽管我们代表 Kubernetes 发布官方公告时会谨慎使用它们
  • 代码示例不需要使用 {{< code_sample >}} 短代码，而且通常不使用会更好
  • 我们允许作者以自己的写作风格撰写文章，只要大多数读者能够理解所表达的观点即可

• 图表指南 旨在用于 Kubernetes 文档，而不是博客文章。与它保持一致仍然是好的，但是

  • 我们更喜欢 SVG 格式而不是栅格图表格式，也更喜欢 SVG 而不是 Mermaid（您仍然可以在注释中捕获 Mermaid 源代码）
  • 无需将图表标注为图 1、图 2 等

其他

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

作为审查者，如果您发现 PR 中存在一些小的、对含义并非至关重要的问题，例如拼写错误或不正确的空格，请在您的评论前加上 nit:。这让作者知道您的反馈的这一部分是非关键的。

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