评审 PR

任何人均可评审文档的拉取请求。 访问 Kubernetes 网站仓库的 pull requests 部分, 可以查看所有待处理的拉取请求(PR)。

评审文档 PR 是将你自己介绍给 Kubernetes 社区的一种很好的方式。 它将有助于你学习代码库并与其他贡献者之间建立相互信任关系。

在评审之前,可以考虑:

准备工作

在你开始评审之前:

  • 阅读 CNCF 行为准则。 确保你会始终遵从其中约定。
  • 保持有礼貌、体谅他人,怀助人为乐初心。
  • 评论时若给出修改建议,也要兼顾 PR 的积极方面。
  • 保持同理心,多考虑他人收到评审意见时的可能反应。
  • 假定大家都是好意的,通过问问题澄清意图。
  • 如果你是有经验的贡献者,请考虑和新贡献者一起合作,提高其产出质量。

评审过程

一般而言,应该使用英语来评审 PR 的内容和样式。 图 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

必须启用 JavaScript 才能查看此页内容

图 1. 评审流程步骤。

  1. 前往 https://github.com/kubernetes/website/pulls, 你会看到所有针对 Kubernetes 网站和文档的待处理 PR。

  2. 使用以下标签(组合)对待处理 PR 进行过滤:

    • cncf-cla: yes (建议):由尚未签署 CLA 的贡献者所发起的 PR 不可以合并。 参考签署 CLA 以了解更多信息。
    • language/en (建议):仅查看英语语言的 PR。
    • size/<尺寸>:过滤特定尺寸(规模)的 PR。 如果你刚入门,可以从较小的 PR 开始。

    此外,确保 PR 没有标记为尚未完成(Work in Progress)。 包含 work in progress 的 PR 通常还没准备好被评审。

  3. 选定 PR 评审之后,可以通过以下方式理解所作的变更:

    • 阅读 PR 描述以理解所作变更,并且阅读所有关联的 Issues。
    • 阅读其他评审人给出的评论。
    • 点击 Files changed Tab 页面,查看被改变的文件和代码行。
    • 滚动到 Conversation Tab 页面下端的 PR 构建检查节区, 预览 Netlify 预览构建中的变更。 以下是一个屏幕截图(这显示了 GitHub 的桌面版外观; 如果你在平板电脑或智能手机设备上进行评审, GitHub 的 Web UI 会略有不同):

      GitHub PR 详细信息,包括 Netlify 预览链接

      要打开预览,请点击 deploy/netlify 行的 Details 链接。

  4. 前往 Files changed Tab 页面,开始你的评审工作。

    1. 点击你希望评论的行旁边的 + 号。

    2. 填写你对该行的评论, 之后选择 Add single comment(如果你只有一条评论) 或者 Start a review(如果你还有其他评论要添加)。

    3. 评论结束时,点击页面顶部的 Review changes。 这里你可以添加你的评论结语(记得留下一些正能量的评论!)、 根据需要批准 PR、请求作者进一步修改等等。 新手应该选择 Comment

      • 避免在完成审查后点击 “Request changes(请求修改)”按钮。 如果在完成进一步修改之前你想阻止某 PR 被合并。你可以在评论中留下一个 “/hold”。 同时在评论中说明你为什么要设置 Hold,并且在必要时指定在什么条件下可以由你或其他评审人取消 Hold。
      • 避免在完成审查后直接点击 “Approve(批准)”按钮。 在大多数情况下,建议在评论区留下一个”/approve(批准)”的评论。

评审清单

评审 PR 时可以从下面的条目入手。

语言和语法

  • 是否存在明显的语言或语法错误?对某事的描述有更好的方式?
  • 是否存在一些过于复杂晦涩的用词,本可以用简单词汇来代替?
  • 是否有些用词、术语或短语可以用不带歧视性的表达方式代替?
  • 用词和大小写方面是否遵从了样式指南
  • 是否有些句子太长,可以改得更短、更简单?
  • 是否某些段落过长,可以考虑使用列表或者表格来表达?

内容

  • Kubernetes 网站上是否别处已经存在类似的内容?
  • 内容本身是否过度依赖于网站范畴之外、独立供应商或者非开源的文档?

网站

  • PR 是否改变或者删除了某页面的标题、slug/别名或者链接锚点? 如果是这样,PR 是否会导致出现新的失效链接? 是否有其他的办法,比如改变页面标题但不改变其 slug?
  • PR 是否引入新的页面?如果是:
    • 该页面是否使用了正确的页面内容类型 及相关联的 Hugo 短代码(shortcodes)?
    • 该页面能否在对应章节的侧面导航中显示?显示得正确么?
    • 该页面是否应出现在网站主页面的列表中?
  • 变更是否正确出现在 Netlify 预览中了? 要对列表、代码段、表格、注释和图像等元素格外留心。

其他

对于 PR 中的小问题,例如拼写错误或者空格问题, 可以在你的评论前面加上 nit:。 这样做可以让作者知道该问题不是一个不得了的大问题。