评阅人和批准人文档

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 命令有：

评阅用 Prow 命令
Prow 命令角色限制描述
/lgtm任何人均可使用，但只有评阅人和批准人使用此命令的时候才会触发自动化操作用来表明你已经完成 PR 的评阅并对其所作变更表示满意
/approve批准人批准某 PR 可以合并
/assign评阅人或批准人指派某人来评阅或批准某 PR
/close评阅人或批准人关闭 Issue 或 PR
/hold任何人添加 do-not-merge/hold 标签，用来表明 PR 不应被自动合并
/hold cancel任何人去掉 do-not-merge/hold 标签

请参考 Prow 命令指南，了解你可以在 PR 中使用的命令的完整列表。

对 Issue 进行诊断和分类

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

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

评判 Issue

  1. 验证 Issue 的合法性
  • 确保 Issue 是关于网站文档的。某些 Issue 可以通过回答问题或者为报告者提供 资源链接来快速关闭。 参考请求支持或代码缺陷报告 节以了解详细信息。
  • 评估该 Issue 是否有价值。
  • 如果 Issue 缺少足够的细节以至于无法采取行动，或者报告者没有通过模版提供 足够信息，可以添加 triage/needs-information 标签。
  • 如果 Issue 同时标注了 lifecycle/stale 和 triage/needs-information 标签，可以直接关闭。
  1. 添加优先级标签（ Issue 判定指南中有优先级标签的详细定义)
Issue 标签
标签描述
priority/critical-urgent应马上处理
priority/important-soon应在 3 个月内处理
priority/important-longterm应在 6 个月内处理
priority/backlog可无限期地推迟，可在人手充足时处理
priority/awaiting-more-evidence占位符，标示 Issue 可能是一个不错的 Issue，避免该 Issue 被忽略或遗忘
help or good first issue适合对 Kubernetes 或 SIG Docs 经验较少的贡献者来处理。更多信息可参考需要帮助和入门候选 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 生命周期标签
标签描述
lifecycle/stale过去 90 天内某 Issue 无人问津，会被自动标记为停滞状态。如果 Issue 没有被 /remove-lifecycle stale 命令重置生命期，就会被自动关闭。
lifecycle/frozen对应的 Issue 即使超过 90 天仍无人处理也不会进入停滞状态。用户手动添加此标签给一些需要保持打开状态超过 90 天的 Issue，例如那些带有 priority/important-longterm 标签的 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）。

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

  1. This issue sounds more like a request for support and less
  2. like an issue specifically for docs. I encourage you to bring
  3. your question to the `#kubernetes-users` channel in
  4. [Kubernetes slack](https://slack.k8s.io/). You can also search
  5. resources like
  6. [Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
  7. for answers to similar questions.
  9. You can also open issues for Kubernetes functionality in
  10. https://github.com/kubernetes/kubernetes.
  12. If this is a documentation issue, please re-open this issue.

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

  1. This sounds more like an issue with the code than an issue with
  2. the documentation. Please open an issue at
  3. https://github.com/kubernetes/kubernetes/issues.
  5. If this is a documentation issue, please re-open this issue.

最后修改 April 21, 2021 at 10:01 PM PST : [zh] Resync contribute section for Chinese localization (3b8786e63)