审查 pull requests

任何人都可以审查文档 pull request。访问 Kubernetes 网站仓库中的 pull requests 部分，查看所有打开的 pull request。

审查文档 pull request 是一个很好的方式来加入 Kubernetes 社区。它帮助你学习代码库并与其他贡献者建立信任。

在审查之前，最好先

在你开始之前

在你开始审查之前

  • 阅读CNCF 行为准则并确保你始终遵守它。
  • 要礼貌、体贴并乐于助人。
  • 评论 PR 的积极方面以及变更本身。
  • 保持同理心，并留意你的评论可能会如何被接收。
  • 假定对方意图良好，并提出澄清性问题。
  • 经验丰富的贡献者，考虑与那些工作需要大量修改的新贡献者结对。

审查流程

通常，以英文审查 pull request 的内容和风格。图 1 概述了审查流程的步骤。每个步骤的详细信息如下。

flowchart LR subgraph fourth[开始审查] direction TB S[ ] -.- M[添加评论] --> N[审查变更] N --> O[新贡献者应
选择 Comment] 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 网站和文档的所有打开的 pull request 列表。

  2. 使用以下一个或所有标签筛选打开的 PR：

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

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

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

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

  4. 转到Files changed（变更的文件）选项卡开始你的审查。

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

    • 完成审查时，避免点击“Request changes”（请求变更）按钮。如果你想在进行进一步修改之前阻止 PR 合并，可以留下一个 "/hold" 评论。说明你设置保留的原因，并可选地指定可以由你或其他审阅者移除保留的条件。

    • 完成审查时，避免点击“Approve”（批准）按钮。大多数情况下，建议留下一个 "/approve" 评论。

审查 checklist

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

语言和语法

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

内容

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

文档

一些需要考虑的检查

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

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

    • 页面是否使用了正确的页面内容类型和相关的 Hugo shortcode？
    • 页面是否在章节的侧边导航中正确显示（或者是否显示）？
    • 页面是否应该出现在文档主页列表中？

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

博客

欢迎通过 Google Doc 或 HackMD 对博文进行早期反馈。请尽早向#sig-docs-blog Slack 频道请求输入。

在审查博客 PR 之前，请熟悉博客指南以及提交博文和案例研究。

确保你也了解常青文章以及如何判断文章是否为常青。

博客文章可能包含直接引语和间接引语。避免为任何归属于某人或已发生对话一部分的内容建议重新措辞——即使你认为原始说话者的语法不正确。对于这些情况，也尽量尊重文章作者建议的标点符号，除非明显错误。

作为项目，我们仅在 Kubernetes 项目愿意承诺无限期维护时，才将博文标记为维护中（front matter 中设置为 evergreen: true）。一些博文绝对值得这样做，我们始终将发布公告标记为常青。如果你不确定如何在此方面进行审查，请与其他贡献者核对。

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

检查 Markdown 源文件是否使用了正确的页面内容类型和/或 layout。

其他

注意琐碎编辑；如果你看到一个你认为是琐碎编辑的变更，请指出该政策（如果它确实是改进，仍然可以接受）。

鼓励进行空白符修复的作者在其 PR 的第一个 commit 中进行，然后在之上添加其他变更。这使得合并和审查都更容易。特别要注意与大量空白符清理同时发生在单个 commit 中的琐碎变更（如果你看到这种情况，鼓励作者修复）。

作为审阅者，如果你发现 PR 中存在与意义不相关的细微问题，例如错别字或不正确的空白符，请在你的评论前加上 nit:。这可以让作者知道你的这部分反馈不是关键性的。

如果你正在考虑批准一个 pull request，并且所有剩余的反馈都被标记为 nit，你仍然可以合并该 PR。在这种情况下，通常有必要就剩余的 nit 打开一个 issue。考虑你是否能够满足将该新 issue 标记为首个良好议题 (Good First Issue) 的要求；如果可以，这些是一个很好的来源。

最后修改于 2025 年 3 月 13 日 上午 10:41 PST：添加博客贡献指南 (815a75d025)