面向批准者和审阅者的评审指南

SIG Docs 的审阅者和批准者在评审变更时会执行一些额外的操作。

每周都会有一位专门的文档批准者自愿负责整理和评审拉取请求（PR）。此人即为当周的“PR 监管员”（PR Wrangler）。更多信息请参阅 PR 监管员排班表。要成为 PR 监管员，请参加每周的 SIG Docs 会议并志愿报名。即使您不在当周的排班表中，仍然可以评审尚未处于活跃评审状态的拉取请求（PR）。

除了轮值制度外，机器人还会根据受影响文件的所有者，为 PR 分配审阅者和批准者。

评审 PR

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

评审拉取请求中描述的所有内容均适用，但审阅者和批准者还应执行以下操作

• 根据需要使用 /assign Prow 命令为 PR 分配特定的审阅者。当需要从代码贡献者那里寻求技术评审时，这一点尤为重要。

  说明

  查看 Markdown 文件顶部的 Front-matter 中的 reviewers 字段，了解谁可以提供技术评审。

• 确保 PR 遵循内容指南和风格指南；如果未遵循，请链接至指南的相关部分告知作者。

• 在适用时使用 GitHub 的请求变更（Request Changes）选项，向 PR 作者建议修改。

• 如果您的建议已得到落实，请使用 /approve 或 /lgtm Prow 命令更改您在 GitHub 上的评审状态。

向他人的 PR 提交代码

留下 PR 评论很有帮助，但有时您可能需要直接向他人的 PR 提交代码。

除非他人明确要求，或者您想恢复一个长期被废弃的 PR，否则不要“接管”他人的工作。虽然短期内可能更快，但这剥夺了对方做出贡献的机会。

所使用的方法取决于您是需要编辑已在 PR 范围内存在的文件，还是编辑 PR 尚未涉及的文件。

如果在以下任一情况下，您无法向他人的 PR 提交代码

• 如果 PR 作者直接将他们的分支推送到 https://github.com/kubernetes/website/ 仓库。只有拥有推送权限的审阅者才能向他人的 PR 提交代码。

  说明

  鼓励作者下次在打开 PR 前将分支推送到他们自己的 fork 中。

• PR 作者明确禁止批准者进行编辑。

用于评审的 Prow 命令

Prow 是一个基于 Kubernetes 的 CI/CD 系统，用于针对拉取请求（PR）运行任务。Prow 启用了聊天机器人风格的命令来处理 Kubernetes 组织中的 GitHub 操作，例如添加和移除标签、关闭议题以及指定批准者。请使用 /<command-name> 格式将 Prow 命令作为 GitHub 评论输入。

审阅者和批准者最常使用的 Prow 命令包括

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

议题分类与整理

通常，SIG Docs 遵循 Kubernetes 议题分类流程并使用相同的标签。

此 GitHub 议题过滤器可以找到可能需要分类的议题。

对议题进行分类

1. 验证议题

   • 确保议题是关于网站文档的。有些议题通过回答问题或将报告者指向相关资源即可快速关闭。详情请参阅支持请求或代码缺陷报告一节。
   • 评估议题是否有价值。
   • 如果议题缺乏足够的可操作细节或模板未填写完整，请添加 triage/needs-information 标签。
   • 如果议题同时带有 lifecycle/stale 和 triage/needs-information 标签，则将其关闭。

2. 添加优先级标签（议题分类指南对优先级标签有详细定义）。

根据您的判断，接手一个议题并为其提交 PR（特别是如果任务简单或与您正在进行的工作相关时）。

如果您对议题分类有疑问，请在 Slack 的 #sig-docs 频道或 kubernetes-sig-docs 邮件列表中提问。

添加和移除议题标签

要添加标签，请以以下任一格式发表评论

• /<label-to-add> (例如，/good-first-issue)
• /<label-category> <label-to-add> (例如，/triage needs-information 或 /language ja)

要移除标签，请以以下任一格式发表评论

• /remove-<label-to-remove> (例如，/remove-help)
• /remove-<label-category> <label-to-remove> (例如，/remove-triage needs-information)

在这两种情况下，标签都必须已存在。如果您尝试添加不存在的标签，该命令将被静默忽略。

有关所有标签的列表，请参阅网站仓库的标签部分。并非所有标签都由 SIG Docs 使用。

议题生命周期标签

议题通常会被快速打开和关闭。然而，有时议题打开后会处于不活跃状态。有时，议题可能需要保持开启超过 90 天。

处理特殊类型的议题

SIG Docs 经常遇到以下类型的议题，足以记录如何处理它们。

重复的议题

如果同一个问题有多个议题处于开启状态，请将它们合并为一个议题。您应决定保留哪个议题（或开启一个新的），然后将所有相关信息移动过来并关联相关的议题。最后，将所有描述同一问题的其他议题标记为 triage/duplicate 并关闭。只处理单个议题可以减少困惑，避免对同一个问题进行重复工作。

死链议题

如果死链议题出现在 API 或 kubectl 文档中，请为其分配 /priority critical-urgent，直到问题被彻底解决。将所有其他死链议题分配为 /priority important-longterm，因为它们必须手动修复。

博客议题

我们预期 Kubernetes 博客条目会随着时间推移而过时。因此，我们只维护发布时间在一年以内的博客条目。如果某个议题关联的博客条目已发布超过一年，您通常应直接关闭该议题，无需修复。

在关闭 PR 时，您可以发送一条包含文章更新和维护链接的消息。

在有正当理由的情况下，可以进行例外处理。

支持请求或代码缺陷报告

有些文档议题实际上是底层代码的问题，或者是教程等内容不工作时的求助请求。对于与文档无关的议题，请使用 kind/support 标签并附上引导请求者去往支持渠道（Slack、Stack Overflow）的评论将其关闭，如果相关，也可以引导其前往对应的仓库以提交功能缺陷（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.

代码缺陷报告的示例回复

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）提交

作为批准者，当您评审拉取请求（PR）时，可能会遇到多种情况，您可能需要

• 建议贡献者压缩（squash）其提交。
• 为贡献者压缩提交。
• 建议贡献者暂时不要压缩。
• 禁止压缩。

建议贡献者压缩：新贡献者可能不知道他们应该压缩 PR 中的提交。如果是这样，请建议他们这样做，提供有用信息的链接，并提出在他们需要时提供帮助。一些有用的链接：

• 开启拉取请求并压缩您的提交（针对文档贡献者）。
• GitHub 工作流（含图示，针对开发者）。

为贡献者压缩提交：如果贡献者在压缩提交方面有困难，或者 PR 有合并的时间压力，您可以代他们进行压缩：

• kubernetes/website 仓库被配置为允许在拉取请求合并时进行压缩。只需选择压缩提交（Squash commits）按钮即可。
• 在 PR 中，如果贡献者启用了维护者管理权限，您可以压缩他们的提交并用结果更新他们的 fork。在压缩之前，建议他们保存并将最新更改推送到 PR。压缩完成后，建议他们将压缩后的提交拉取到本地仓库中。
• 您可以通过使用标签让 Tide/GitHub 执行压缩，或者在合并 PR 时点击压缩提交按钮，让 GitHub 执行压缩。

建议贡献者避免压缩

• 如果某个提交做了错误或不当的操作，而后续的提交撤销了这个错误，则不要压缩这些提交。尽管 GitHub 上 PR 的“Files changed”标签页和 Netlify 预览看起来都正常，但合并该 PR 可能会为其他人产生 rebase 或合并冲突。请根据您的判断进行干预，以避免给其他贡献者带来风险。

永远不要压缩

• 如果您正在启动本地化工作或发布新版本的文档，且您合并的分支并非来自用户的 fork，则永远不要压缩提交。不压缩对于维护这些文件的提交历史至关重要。