评阅 PRs

任何人均可评阅文档的拉取请求。访问 Kubernetes 网站仓库的 pull requests 部分可以查看所有待处理的拉取请求（PRs）。

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

在评阅之前，可以考虑：

准备工作

在你开始评阅之前：

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

评阅过程

一般而言，应该使用英语来评阅 PR 的内容和样式。

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

  2. 使用以下标签（组合）对待处理 PRs 进行过滤：

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

    此外，确保 PR 没有标记为尚未完成（Work in Progress）。 包含 work in progress 的 PRs 通常还没准备好被评阅。

  3. 选定 PR 评阅之后，可以通过以下方式理解所作的变更：

    • 阅读 PR 描述以理解所作变更，并且阅读所有关联的 Issues
    • 阅读其他评阅人给出的评论
    • 点击 Files changed Tab 页面，查看被改变的文件和代码行
    • 滚动到 Conversation Tab 页面下端的 PR 构建检查节区，点击 deploy/netlify 行的 Details 链接，预览 Netlify 预览构建所生成的结果

  4. 前往 Files changed Tab 页面，开始你的评阅工作

    1. 点击你希望评论的行旁边的 + 号
    2. 填写你对该行的评论，之后或者选择Add single comment （如果你只有一条评论） 或者 Start a review （如果你还有其他评论要添加）
    3. 评论结束时，点击页面顶部的 Review changes。这里你可以添加你的评论结语 （记得留下一些正能量的评论！）、根据需要批准 PR、请求作者进一步修改等等。 新手应该选择 Comment。

评阅清单

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

语言和语法

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

内容

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

网站

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

其他

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