面向审批者和审阅者的审阅

SIG Docs 的 审阅者审批者 在审阅变更时会做一些额外的工作。

每周都会有一位特定的文档审批者志愿者来分类处理和审阅拉取请求。此人是当周的“PR 管理员”。有关更多信息,请参阅 PR 管理员日程表。要成为 PR 管理员,请参加每周的 SIG Docs 会议并自愿报名。即使您不在本周的日程表中,您仍然可以审阅尚未进入积极审阅状态的拉取请求 (PR)。

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

审阅 PR

Kubernetes 文档遵循 Kubernetes 代码审阅流程

审阅拉取请求 中描述的一切都适用,但审阅者和审批者还应做以下工作:

  • 根据需要使用 /assign Prow 命令为 PR 分配特定的审阅者。在请求代码贡献者的技术审阅时,这一点尤其重要。

  • 确保 PR 遵循 内容风格 指南;如果 PR 不遵循,请将作者链接到指南的相关部分。

  • 在适用时使用 GitHub 的 Request Changes 选项向 PR 作者建议更改。

  • 如果您的建议已实现,请使用 /approve/lgtm Prow 命令在 GitHub 中更改您的审阅状态。

提交到其他人的 PR 中

在 PR 中留言很有帮助,但有时您可能需要直接提交到其他人的 PR 中。

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

您使用的流程取决于您是需要编辑 PR 范围内已有的文件,还是 PR 尚未涉及的文件。

如果发生以下任何一种情况,您都无法提交到其他人的 PR 中:

  • 如果 PR 作者将其分支直接推送到 https://github.com/kubernetes/website/ 仓库。只有具有推送权限的审阅者才能提交到其他用户的 PR。

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

Prow 审阅命令

Prow 是基于 Kubernetes 的 CI/CD 系统,它针对拉取请求 (PR) 运行 Job。Prow 启用了聊天机器人式的命令,用于处理 Kubernetes 组织中的 GitHub 操作,例如添加和移除标签、关闭 Issue 以及分配审批者。使用 /<command-name> 格式将 Prow 命令作为 GitHub 评论输入。

审阅者和审批者最常用的 Prow 命令是:

Prow 审阅命令
Prow 命令角色限制描述
/lgtm组织成员表示您已完成 PR 审阅并对更改感到满意。
/approve审批者批准 PR 合并。
/assign任何人将某人分配给 PR 进行审阅或批准
/close组织成员关闭 Issue 或 PR。
/hold任何人添加 do-not-merge/hold 标签,表示 PR 无法自动合并。
/hold cancel任何人移除 do-not-merge/hold 标签。

要查看您可以在 PR 中使用的命令,请参阅 Prow 命令参考

分类处理和归类 Issue

通常,SIG Docs 遵循 Kubernetes Issue 分类处理 流程并使用相同的标签。

这个 GitHub Issue 筛选条件 会找到可能需要分类处理的 Issue。

分类处理 Issue

  1. 验证 Issue

    • 确保 Issue 是关于网站文档的。通过回答问题或将报告者指向资源,一些 Issue 可以快速关闭。有关详细信息,请参阅 支持请求或代码 Bug 报告 部分。
    • 评估 Issue 是否有价值。
    • 如果 Issue 没有足够的详细信息可供操作或模板填写不充分,请添加 triage/needs-information 标签。
    • 如果 Issue 同时具有 lifecycle/staletriage/needs-information 标签,则关闭该 Issue。
  2. 添加优先级标签(Issue 分类处理指南 中详细定义了优先级标签)

Issue 标签
标签描述
priority/critical-urgent立即处理此 Issue。
priority/important-soon在 3 个月内处理此 Issue。
priority/important-longterm在 6 个月内处理此 Issue。
priority/backlog无限期推迟。资源可用时处理。
priority/awaiting-more-evidence潜在有价值 Issue 的占位符,以免丢失。
helpgood first issue非常适合几乎没有 Kubernetes 或 SIG Docs 经验的人。有关更多信息,请参阅 Help Wanted 和 Good First Issue 标签

您可以自行决定承担某个 Issue 并为其提交 PR(特别是如果它是快速的任务或与您正在进行的工作相关)。

如果您对分类处理 Issue 有疑问,请在 Slack 上的 #sig-docskubernetes-sig-docs 邮件列表 中提问。

添加和移除 Issue 标签

要添加标签,请使用以下格式之一留言:

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

要移除标签,请使用以下格式之一留言:

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

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

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

Issue 生命周期标签

Issue 通常会快速打开和关闭。但是,有时 Issue 打开后处于非活动状态。其他时候,Issue 可能需要保持开放超过 90 天。

Issue 生命周期标签
标签描述
lifecycle/stale90 天没有活动后,Issue 会自动被标记为 stale(陈旧)。如果未使用 /remove-lifecycle stale 命令手动恢复其生命周期,Issue 将自动关闭。
lifecycle/frozen带有此标签的 Issue 在 90 天不活动后不会变为陈旧。用户会手动将此标签添加到需要保持开放时间远远超过 90 天的 Issue,例如带有 priority/important-longterm 标签的 Issue。

处理特殊 Issue 类型

SIG Docs 经常遇到以下类型的 Issue,因此需要记录如何处理它们。

重复 Issue

如果一个问题有一个或多个 Issue 处于打开状态,请将它们合并为一个 Issue。您应该决定保留哪个 Issue 处于打开状态(或打开一个新 Issue),然后迁移所有相关信息并链接相关 Issue。最后,使用 triage/duplicate 标签标记描述同一问题的所有其他 Issue 并将其关闭。只处理一个 Issue 可以减少混淆,避免重复工作。

如果死链 Issue 存在于 API 或 kubectl 文档中,请将其分配 /priority critical-urgent 标签,直到完全理解问题。将所有其他死链 Issue 分配 /priority important-longterm 标签,因为它们必须手动修复。

博客 Issue

我们预计 Kubernetes 博客 文章会随着时间推移而过时。因此,我们只维护发布不到一年的博客文章。如果 Issue 与一年多前的博客文章相关,通常您应该关闭该 Issue 而不进行修复。

在关闭 PR 时发送的消息中,您可以附上 文章更新和维护 的链接。

在有相关正当理由的情况下可以破例。

支持请求或代码 Bug 报告

有些文档 Issue 实际上是底层代码的问题,或者是当某个东西(例如教程)无法工作时请求帮助。对于与文档无关的 Issue,请使用 kind/support 标签关闭 Issue,并附上评论,指导请求者前往支持渠道(Slack、Stack Overflow),如果相关,还应告知他们提交功能 Bug Issue 的仓库(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.

代码 Bug 报告的回复示例

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 提交。
  • 为贡献者 Squash 提交。
  • 建议贡献者暂时不要 Squash。
  • 阻止 Squash。

建议贡献者 Squash:新贡献者可能不知道应该在拉取请求 (PR) 中 Squash 提交。如果是这种情况,请建议他们这样做,提供有用信息的链接,并在他们需要时提供帮助。一些有用的链接:

为贡献者 Squash 提交:如果贡献者在 Squash 提交方面可能遇到困难,或者存在合并 PR 的时间压力,您可以代劳进行 Squash:

  • kubernetes/website 仓库已配置为允许在合并拉取请求时 Squash。只需选择 Squash commits 按钮即可。
  • 在 PR 中,如果贡献者允许维护者管理 PR,您可以 Squash 他们的提交并使用结果更新他们的 Fork。在 Squash 之前,建议他们保存并将最新的更改推送到 PR 中。在 Squash 之后,建议他们将 Squash 后的提交 Pull 到本地克隆中。
  • 您可以通过使用标签让 Tide / GitHub 执行 Squash,或者在合并 PR 时单击 Squash commits 按钮来让 GitHub Squash 提交。

建议贡献者避免 Squash

  • 如果某个提交导致了错误或不当操作,而最后一个提交回滚了此错误,则不要 Squash 这些提交。即使 GitHub 上 PR 中的“Files changed”选项卡和 Netlify 预览看起来都没问题,合并此 PR 可能会给其他人造成 Rebase 或合并冲突。请酌情介入,以避免给其他贡献者带来风险。

切勿 Squash

  • 如果您正在进行本地化或发布新版本的文档,并且合并的分支不是来自用户的 Fork,切勿 Squash 提交。不 Squash 至关重要,因为您必须维护这些文件的提交历史记录。
上次修改于 2025 年 3 月 13 日 上午 10:41 PST: 添加博客贡献指南 (815a75d025)