评阅变更

• 1: 评审 PR
• 2: 评阅人和批准人文档

1 - 评审 PR

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

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

在评审之前，可以考虑：

• 阅读内容指南和 样式指南以便给出有价值的评论。
• 了解 Kubernetes 文档社区中不同的角色和职责。

准备工作

在你开始评审之前：

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

评审过程

一般而言，应该使用英语来评审 PR 的内容和样式。 图 1 概述了评审流程的各个步骤。 每个步骤的详细信息如下。

图 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 会略有不同）：

     

     要打开预览，请点击 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 时可以从下面的条目入手。

语言和语法

• 是否存在明显的语言或语法错误？对某事的描述有更好的方式？
  • 关注作者正在更改的页面部分的语言和语法。除非作者明确打算更新整个页面，否则他们没有义务修复页面上的所有问题。
  • 当一个 PR 更新现有页面时，你应专注于评审正在更新的页面部分。你应评审所更改内容的技术和编辑的正确性。 如果你发现页面上的一些错误与 PR 作者尝试解决的问题没有直接关系， 则应将其视为一个单独的 Issue（首先检查是否存在与此相关的 Issue）。
  • 要特别注意那些移动内容的 PR。如果作者重命名一个页面或合并两个页面， 我们（Kubernetes SIG Docs）通常应避免要求该作者修复可能在所移动的内容中发现的所有语法或拼写错误。
• 是否存在一些过于复杂晦涩的用词，本可以用简单词汇来代替？
• 是否有些用词、术语或短语可以用不带歧视性的表达方式代替？
• 用词和大小写方面是否遵从了样式指南？
• 是否有些句子太长，可以改得更短、更简单？
• 是否某些段落过长，可以考虑使用列表或者表格来表达？

内容

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

网站

• PR 是否改变或者删除了某页面的标题、slug/别名或者链接锚点？ 如果是这样，PR 是否会导致出现新的失效链接？ 是否有其他的办法，比如改变页面标题但不改变其 slug？

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

  • 该页面是否使用了正确的页面内容类型 及相关联的 Hugo 短代码（shortcodes）？
  • 该页面能否在对应章节的侧面导航中显示？显示得正确么？
  • 该页面是否应出现在网站主页面的列表中？

• 变更是否正确出现在 Netlify 预览中了？ 要对列表、代码段、表格、注释和图像等元素格外留心。

博客

• 欢迎通过 Google Doc 或 HackMD 对博客文章提供早期反馈。请尽早通过 #sig-docs-blog Slack 频道请求输入。
• 在审查博客的拉取请求（PR）之前，请熟悉提交博客文章和案例研究的相关指南。

• 我们愿意镜像任何发布到 https://kubernetes.dev/blog/（贡献者博客）的博客文章，前提是：
  • 镜像的文章应与原文有相同的发布日期（理想情况下，发布时间也应相同，但在特殊情况下， 可以设置一个最多晚于原时间 12 小时的时间戳）。
  • 对于那些原始文章已被合并到 https://kubernetes.dev/ 的拉取请求（PR），在原始文章和镜像文章发布之间， 主博客上没有（也不会有）任何文章发布。这是因为我们不希望除了在 RSS 等订阅源的末端之外添加新的文章到人们的订阅源中。
  • 原始文章不应违反任何强烈推荐的审核指南或社区规范。
  • 应为镜像文章设置规范URL（canonical URL），指向原始文章的URL（你可以使用预览来预测URL并在实际发布前填写）。 为此，请在前置元数据中使用 canonicalUrl 字段。

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

  这一考量同样适用于镜像文章；虽然我们愿意考虑镜像所有有效的贡献者文章（如果有拉取请求的话）， 我们并不会镜像所有的文章。

• 我们仅在 Kubernetes 项目愿意无限期维护某博客文章的情况下，才将其标记为持续维护状态（在前置元数据中设置 evergreen: true）。某些博客文章确实值得这样做，而且我们总是将版本发布通知标记为持续维护状态。 如果你不确定如何在此点上进行审查，请与其他贡献者确认。

• 内容指南无条件地适用于博客文章及添加这些文章的拉取请求（PR）。 请注意，指南中的一些限制规定仅适用于文档，并不适用于博客文章。

• 样式指南大部分也适用于博客的拉取请求（PR）， 但我们做出了一些例外。

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

• 图表指南主要针对 Kubernetes 文档， 而不是博客文章。尽管如此，保持一致仍然是好的，但是：
  • 我们更倾向于使用 SVG 而不是栅格图像格式，也优于 Mermaid（你仍然可以在注释中保留 Mermaid 源码）。
  • 不需要将图表标注为图 1、图 2 等。

其他

• 查阅 Trivial Edits； 如果你看到某个变更在你看来是一个 Trivial Edit，请向作者指明这项政策（如果该变更确实会有所改进，那仍然可以接受）。
• 鼓励作者们在第一次发 PR 时修复一些空格相关的问题，在随后的 PR 中增加其他更改。 这样更便于合并和评审。尤其要注意在单个 commit 中大量空格清理附带的微小变更（如果你看到，请鼓励作者进行修复）。

作为一名 Reviewer，如果你发现 PR 有一些无关紧要的小问题，例如拼写错误或不正确的空格， 可以在你的评论前面加上 nit:。这样做可以让作者知道该问题不是一个不得了的大问题。

如果你正在考虑批准一个 PR，并且所有剩余的反馈都被标记为 nit，那么你确实可以合并该 PR。 在这种情况下，你需要针对剩余的 nit 发帖登记一个 Issue。 考虑一下是否能把这些新 Issue 标记为 Good First Issue。 如果可以，这就是这类 Issue 的良好来源。

2 - 评阅人和批准人文档

SIG Docs 评阅人（Reviewers） 和批准人（Approvers） 在对变更进行评审时需要做一些额外的事情。

每周都有一个特定的文档批准人自愿负责对 PR 进行分类和评阅。 此角色称作该周的“PR 管理者（PR Wrangler）”。 相关信息可参考 PR Wrangler 排班表。 要成为 PR Wangler，需要参加每周的 SIG Docs 例会，并自愿报名。 即使当前这周排班没有轮到你，你仍可以评阅那些尚未被积极评阅的 PRs。

除了上述的轮值安排，后台机器人也会为基于所影响的文件来为 PR 指派评阅人和批准人。

评阅 PR

Kubernetes 文档遵循 Kubernetes 代码评阅流程。

评阅 PR 文档中所描述的所有规程都适用， 不过评阅人和批准人还要做以下工作：

• 根据需要使用 Prow 命令 /assign 指派特定的评阅人。如果某个 PR 需要来自代码贡献者的技术审核时，这一点非常重要。

  说明：

  你可以查看 Markdown 文件的文件头，其中的 reviewers 字段给出了哪些人可以为文档提供技术审核。

• 确保 PR 遵从内容指南和样式指南； 如果 PR 没有达到要求，指引作者阅读指南中的相关部分。

• 适当的时候使用 GitHub Request Changes 选项，建议 PR 作者实施所建议的修改。

• 当你所提供的建议被采纳后，在 GitHub 中使用 /approve 或 /lgtm Prow 命令，改变评审状态。

提交到他人的 PR

为 PR 留下评语是很有用的，不过有时候你需要向他人的 PR 提交内容。

除非他人明确请求你的帮助或者你希望重启一个被放弃很久的 PR，不要“接手”他人的工作。 尽管短期看来这样做可以提高效率，但是也剥夺了他人提交贡献的机会。

你所要遵循的流程取决于你需要编辑已经在 PR 范畴的文件，还是 PR 尚未触碰的文件。

如果处于下列情况之一，你不可以向别人的 PR 提交内容：

• 如果 PR 作者是直接将自己的分支提交到 https://github.com/kubernetes/website/ 仓库。只有具有推送权限的评阅人才可以向他人的 PR 提交内容。

  说明：

  我们应鼓励作者下次将分支推送到自己的克隆副本之后再发起 PR。

• PR 作者明确地禁止批准人编辑他/她的 PR。

评阅用的 Prow 命令

Prow 是基于 Kubernetes 的 CI/CD 系统，基于拉取请求（PR）的触发运行不同任务。 Prow 使得我们可以使用会话机器人一样的命令跨整个 Kubernetes 组织处理 GitHub 动作，例如添加和删除标签、关闭 Issues 以及指派批准人等等。你可以使用 /<命令名称> 的形式以 GitHub 评论的方式输入 Prow 命令。

评阅人和批准人最常用的 Prow 命令有：

要查看可以在 PR 中使用的命令，请参阅 Prow 命令指南。

对 Issue 进行诊断和分类

一般而言，SIG Docs 遵从 Kubernetes issue 判定 流程并使用相同的标签。

此 GitHub Issue 过滤器 可以用来查找需要评判的 Issues。

评判 Issue

1. 验证 Issue 的合法性

• 确保 Issue 是关于网站文档的。某些 Issue 可以通过回答问题或者为报告者提供 资源链接来快速关闭。 参考请求支持或代码缺陷报告 节以了解详细信息。
• 评估该 Issue 是否有价值。
• 如果 Issue 缺少足够的细节以至于无法采取行动，或者报告者没有通过模版提供 足够信息，可以添加 triage/needs-information 标签。
• 如果 Issue 同时标注了 lifecycle/stale 和 triage/needs-information 标签，可以直接关闭。

2. 添加优先级标签（ Issue 判定指南中有优先级标签的详细定义)

基于你自己的判断，你可以选择某 Issue 来处理，为之发起 PR （尤其是那些可以很快处理或与你已经在做的工作相关的 Issue）。

如果你对 Issue 评判有任何问题，可以在 #sig-docs Slack 频道或者 kubernetes-sig-docs 邮件列表 中提问。

添加和删除 Issue 标签

要添加标签，可以用以下形式对 PR 进行评论：

• /<要添加的标签> （例如, /good-first-issue）
• /<标签类别> <要添加的标签> （例如，/triage needs-information 或 /language ja）

要移除某个标签，可以用以下形式对 PR 进行评论：

• /remove-<要移除的标签> （例如，/remove-help）
• /remove-<标签类别> <要移除的标签> （例如，/remove-triage needs-information）

在以上两种情况下，标签都必须合法存在。如果你尝试添加一个尚不存在的标签， 对应的命令会被悄悄忽略。

关于所有标签的完整列表，可以参考 Website 仓库的标签节。 实际上，SIG Docs 并没有使用全部标签。

Issue 生命周期标签

Issues 通常都可以快速创建并关闭。 不过也有些时候，某个 Issue 被创建之后会长期处于非活跃状态。 也有一些时候，即使超过 90 天，某个 Issue 仍应保持打开状态。

处理特殊的 Issue 类型

SIG Docs 常常会遇到以下类型的 Issue，因此对其处理方式描述如下。

重复的 Issue

如果针对同一个问题有不止一个打开的 Issue，可以将其合并为一个 Issue。 你需要决定保留哪个 Issue 为打开状态（或者重新登记一个新的 Issue）， 然后将所有相关的信息复制过去并提供对关联 Issues 的链接。 最后，将所有其他描述同一问题的 Issue 标记为 triage/duplicate 并关闭之。 保持只有一个 Issue 待处理有助于减少困惑，避免在同一问题上发生重复劳动。

失效链接 Issues

如果失效链接是关于 API 或者 kubectl 文档的，可以将其标记为 /priority critical-urgent，直到问题原因被弄清楚为止。 对于其他的链接失效问题，可以标记 /priority important-longterm， 因为这些问题都需要手动处理。

博客问题

我们预期 Kubernetes 博客条目随着时间推移都会过期。 因此，我们只维护一年内的博客条目。 如果某个 Issue 是与某个超过一年的博客条目有关的，可以直接关闭 Issue，不必修复。

请求支持或代码缺陷报告

某些文档 Issues 实际上是关于底层代码的 Issue 或者在某方面请求协助的问题， 例如某个教程无法正常工作。 对于与文档无关的 Issues，关闭它并打上标签 kind/support，可以通过评论 告知请求者其他支持渠道（Slack、Stack Overflow）。 如果有相关的其他仓库，可以告诉请求者应该在哪个仓库登记与功能特性相关的 Issues （通常会是 kubernetes/kubernetes）。

下面是对支持请求的回复示例：

This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](https://slack.k8s.io/). You can also search
resources like
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.

You can also open issues for Kubernetes functionality in
https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

对代码缺陷 Issue 的回复示例：

This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

压缩（Squashing）提交

作为一名 Approver，当你评审 PR 时，可能会遇到以下几种情况：

• 建议贡献者压缩他们的提交。
• 协助贡献者压缩提交。
• 建议贡献者先不要压缩提交。
• 阻止压缩提交。

建议贡献者压缩提交：新贡献者可能不知道要压缩 PR 中的提交。 如果是这种情况，Approver 要给出压缩提交的建议，并贴附有用的链接， 并在贡献者需要帮助时伸出援手。这里有一些有用的链接：

• 协助文档贡献者提 PR 和压缩提交。
• 面向开发者包括插图在内的 GitHub 工作流程。

协助贡献者压缩提交：如果贡献者压缩提交遇到难题或合并 PR 的时间紧迫， 你可以协助贡献者执行压缩提交的操作。

• kubernetes/website 仓库被配置为允许压缩提交后合并 PR。 你只需选择 Squash commits 按钮。
• 在 PR 中，如果贡献者允许 Maintainer 们管理 PR，你就可以为他们压缩提交并将其 fork 更新为最新结果。 在你执行压缩提交之后，请建议贡献者将压缩后的提交拉到他们本地的克隆副本。
• 你可以使用标签让 GitHub 压缩提交，这样 Tide / GitHub 就会对提交执行压缩； 你还可以在合并 PR 时点选 Squash commits 按钮。

建议贡献者避免压缩提交

• 如果一个提交做了一些破坏性或不明智的修改，那最后一个提交可用于回滚错误，这种情况不要压缩提交。 即使通过 GitHub 上 PR 中的 "Files changed" 页签以及 Netlify 预览看起来都正常， 合并这种 PR 可能会在其他 fork 中造成 rebase 或合并冲突。 你看到这种情况要进行合理的干预，避免对其他贡献者造成麻烦。

千万不要压缩提交

• 如果你为新版本发起了一次本地化批量作业或为新版发布许多文档，那你要合并到的分支将与用户 fork 的分支不同， 这种情况千万不要压缩提交。之所以不压缩提交，是因为你必须保持这些文件的提交历史记录。