面向审批者和审阅者的审阅
SIG Docs 的 审阅者 和 审批者 在审阅变更时会做一些额外的工作。
每周都会有一位特定的文档审批者志愿者来分类处理和审阅拉取请求。此人是当周的“PR 管理员”。有关更多信息,请参阅 PR 管理员日程表。要成为 PR 管理员,请参加每周的 SIG Docs 会议并自愿报名。即使您不在本周的日程表中,您仍然可以审阅尚未进入积极审阅状态的拉取请求 (PR)。
除了轮值,机器人会根据受影响文件的所有者为 PR 分配审阅者和审批者。
审阅 PR
Kubernetes 文档遵循 Kubernetes 代码审阅流程。
在 审阅拉取请求 中描述的一切都适用,但审阅者和审批者还应做以下工作:
根据需要使用
/assign
Prow 命令为 PR 分配特定的审阅者。在请求代码贡献者的技术审阅时,这一点尤其重要。注意
查看 Markdown 文件顶部的 front-matter 中的reviewers
字段,了解谁可以提供技术审阅。在适用时使用 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) 运行 Job。Prow 启用了聊天机器人式的命令,用于处理 Kubernetes 组织中的 GitHub 操作,例如添加和移除标签、关闭 Issue 以及分配审批者。使用 /<command-name>
格式将 Prow 命令作为 GitHub 评论输入。
审阅者和审批者最常用的 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
验证 Issue
- 确保 Issue 是关于网站文档的。通过回答问题或将报告者指向资源,一些 Issue 可以快速关闭。有关详细信息,请参阅 支持请求或代码 Bug 报告 部分。
- 评估 Issue 是否有价值。
- 如果 Issue 没有足够的详细信息可供操作或模板填写不充分,请添加
triage/needs-information
标签。 - 如果 Issue 同时具有
lifecycle/stale
和triage/needs-information
标签,则关闭该 Issue。
添加优先级标签(Issue 分类处理指南 中详细定义了优先级标签)
标签 | 描述 |
---|---|
priority/critical-urgent | 立即处理此 Issue。 |
priority/important-soon | 在 3 个月内处理此 Issue。 |
priority/important-longterm | 在 6 个月内处理此 Issue。 |
priority/backlog | 无限期推迟。资源可用时处理。 |
priority/awaiting-more-evidence | 潜在有价值 Issue 的占位符,以免丢失。 |
help 或 good first issue | 非常适合几乎没有 Kubernetes 或 SIG Docs 经验的人。有关更多信息,请参阅 Help Wanted 和 Good First Issue 标签。 |
您可以自行决定承担某个 Issue 并为其提交 PR(特别是如果它是快速的任务或与您正在进行的工作相关)。
如果您对分类处理 Issue 有疑问,请在 Slack 上的 #sig-docs
或 kubernetes-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 天。
标签 | 描述 |
---|---|
lifecycle/stale | 90 天没有活动后,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
如果死链 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 提交。
- 面向开发者的GitHub 工作流(包含图表)。
为贡献者 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 至关重要,因为您必须维护这些文件的提交历史记录。