审查拉取请求

任何人都可以审查文档的拉取请求。请访问 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 网页界面会略有不同）
      GitHub pull request details including link to Netlify preview
      要打开预览，请点击检查列表中 deploy/netlify 行的“详细信息”链接。

  4. 前往“已更改文件”选项卡开始你的审查。

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

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

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

审查清单

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

语言和语法

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

内容

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

文档

一些需要考虑的检查

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

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

    • 页面是否使用了正确的 页面内容类型 和相关的 Hugo 短代码？
    • 页面是否在章节的侧边导航中（或是否出现）正确显示？
    • 页面是否应显示在 Docs Home 列表中？

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

博客

通过 Google Doc 或 HackMD 即可对博客文章提供早期反馈。请尽早向 #sig-docs-blog Slack 频道请求输入。

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

请确保你也了解 长期维护的文章以及如何判断一篇文章是否是长期维护的。

博客文章可能包含 直接引用和 间接引用。即使你认为原始说话者的语法不正确，也要避免建议修改被归因于某人或已发生的对话的内容。对于这些情况，也请尽量尊重文章作者建议的标点符号，除非它明显错误。

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

《内容指南》无条件适用于博客文章及其添加它们的 PR。请注意，指南中的某些限制声明仅与文档相关；这些限制不适用于博客文章。

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

其他

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

鼓励进行空白字符修复的作者在 PR 的第一个 commit 中进行，然后在上面添加其他更改。这使得合并和审查都更容易。特别留意发生在单个 commit 中，并伴有大量空白字符清理的微小更改（如果你看到这种情况，请鼓励作者进行修复）。

作为审查者，如果你识别出 PR 的小问题，而这些问题并不影响核心意义，例如拼写错误或不正确的空格，请在评论前加上 nit:。这会让作者知道你反馈的这部分是非关键的。

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

最后修改时间：2025 年 3 月 13 日上午 10:41 PST：添加博客贡献指南（815a75d025）