参与 SIG Docs

• 1: 角色与责任
• 2: Issue 管理者
• 3: PR 管理者

1 - 角色与责任

任何人都可以为 Kubernetes 作出贡献。随着你对 SIG Docs 的贡献增多，你可以申请 社区内不同级别的成员资格。 这些角色使得你可以在社区中承担更多的责任。 每个角色都需要更多的时间和投入。具体包括：

• 任何人（Anyone）：为 Kubernetes 文档作出贡献的普通贡献者。
• 成员（Members）：可以对 Issue 进行分派和判别，对 PR 提出无约束性的评审意见。
• 评审人（Reviewers）：可以领导对文档 PR 的评审，可以对变更的质量进行判别。
• 批准人（Approvers）：可以领导对文档的评审并合并变更。

任何人（Anyone）

任何拥有 GitHub 账号的人都可以对 Kubernetes 作出贡献。SIG Docs 欢迎所有新的贡献者。

任何人都可以：

• 在任何 Kubernetes 仓库，包括 kubernetes/website 上报告 Issue。
• 对某 PR 给出无约束力的反馈信息
• 为本地化提供帮助
• 在 Slack 或 SIG Docs 邮件列表 上提出改进建议。

在签署了 CLA 之后，任何人还可以：

• 发起拉取请求（PR），改进现有内容、添加新内容、撰写博客或者案例分析
• 创建示意图、图形资产或者嵌入式的截屏和视频内容

进一步的详细信息，可参见贡献新内容。

成员（Members）

成员是指那些对 kubernetes/website 提交很多拉取请求（PR）的人。 成员都要加入 Kubernetes GitHub 组织。

成员可以：

• 执行任何人节区所列举操作

• 使用 /lgtm 评论添加 LGTM (looks good to me（我觉得可以）) 标签到某个 PR

  说明：

  使用 /lgtm 会触发自动化机制。如果你希望提供非约束性的批准意见， 直接回复 "LGTM" 也是可以的。

• 利用 /hold 评论来阻止某个 PR 被合并

• 使用 /assign 评论为某个 PR 指定评审人

• 对 PR 提供非约束性的评审意见

• 使用自动化机制来对 Issue 进行判别和分类

• 为新功能特性撰写文档

成为一个成员

在你成功地提交至少 5 个 PR 并满足 相关条件 之后：

1. 找到两个评审人或批准人为你的成员身份提供 担保。

   通过 Kubernetes Slack 上的 #sig-docs 频道 或者 SIG Docs 邮件列表 来寻找为你担保的人。

   说明：

   不要单独发送邮件给某个 SIG Docs 成员或在 Slack 中与其私聊。 在提交申请之前，一定要先确定担保人。

2. 在 kubernetes/org 仓库 使用 Organization Membership Request Issue 模板登记一个 Issue。

3. 告知你的担保人你所创建的 Issue，你可以：

   • 在 Issue 中 @<GitHub-username> 提及他们的 GitHub 用户名
   • 通过 Slack 或 email 直接发送给他们 Issue 链接

   担保人会通过 +1 投票来批准你的请求。一旦你的担保人批准了该请求， 某个 Kubernetes GitHub 管理员会将你添加为组织成员。恭喜！

   如果你的成员请求未被接受，你会收到一些反馈。 当处理完反馈意见之后，可以再次发起申请。

4. 登录你的邮件账户，接受来自 Kubernetes GitHub 组织发出的成员邀请。

   说明：

   GitHub 会将邀请发送到你的账户中所设置的默认邮件地址。
   

评审人（Reviewers）

评审人负责评审悬决的 PR。 与成员所给的反馈不同，身为 PR 作者必须处理评审人的反馈。 评审人是 @kubernetes/sig-docs-{language}-reviews GitHub 团队的成员。

评审人可以：

• 执行任何人和成员节区所列举的操作

• 评审 PR 并提供具约束性的反馈信息

  说明：

  要提供非约束性的反馈，可以在你的评语之前添加 "Optionally: " 这样的说法。
  

• 编辑代码中用户可见的字符串

• 改进代码注释

你可以是 SIG Docs 的评审人，也可以是某个主题领域的文档的评审人。

为 PR 指派评审人

自动化引擎会为每个 PR 自动指派评审人。 你可以通过为 PR 添加评论 /assign [@_github_handle] 来请求某个特定评审人来评审。

如果所指派的评审人未能及时评审，其他的评审人也可以参与进来。 你可以根据需要指派技术评审人。

使用 /lgtm

LGTM 代表的是 “Looks Good To Me （我觉得可以）”，用来标示某个 PR 在技术上是准确的，可以被合并。 所有 PR 都需要来自某评审人的 /lgtm 评论和来自某批准人的 /approve 评论。

来自评审人的 /lgtm 评论是具有约束性的，会触发自动化引擎添加 lgtm 标签。

成为评审人

当你满足相关条件时， 你可以成为一个 SIG Docs 评审人。 来自其他 SIG 的评审人必须为 SIG Docs 单独申请评审人资格。

申请流程如下：

1. 发起 PR，将你的 GitHub 用户名添加到 kubernetes/website 仓库中 OWNERS_ALIASES 文件的对应节区。

   说明：

   如果你不确定要添加到哪个位置，可以将自己添加到 sig-docs-en-reviews。

2. 将 PR 指派给一个或多个 SIG Docs 批准人（sig-docs-{language}-owners 下列举的用户名）。

申请被批准之后，SIG Docs Leads 之一会将你添加到合适的 GitHub 团队。 一旦添加完成，@k8s-ci-robot 会在处理未来的 PR 时，将 PR 指派给你或者建议你来评审某 PR。

批准人（Approvers）

批准人负责评审和批准 PR 以将其合并。 批准人是 @kubernetes/sig-docs-{language}-owners GitHub 团队的成员。

批准人可以执行以下操作：

• 执行列举在任何人、成员和评审人节区的操作
• 通过使用 /approve 评论来批准、合并 PR，发布贡献者所贡献的内容。
• 就样式指南给出改进建议
• 对文档测试给出改进建议
• 对 Kubernetes 网站或其他工具给出改进建议

如果某个 PR 已有 /lgtm 标签，或者批准人再回复一个 /lgtm，则这个 PR 会自动合并。 SIG Docs 批准人应该只在不需要额外的技术评审的情况下才可以标记 /lgtm。

批准 PR

只有批准人和 SIG Docs Leads 可以将 PR 合并到网站仓库。 这意味着以下责任：

• 批准人可以使用 /approve 命令将 PR 合并到仓库中。

  警告：

  不小心的合并可能会破坏整个站点。在执行合并操作时，务必小心。
  

• 确保所提议的变更满足文档内容指南要求。

  如果有问题或者疑惑，可以根据需要请他人帮助评审。

• 在 /approve PR 之前，须验证 Netlify 测试是否正常通过。

  

• 在批准之前，请访问 Netlify 的页面预览来确保变更内容可正常显示。

• 参与 PR 管理者轮值排班 执行时长为一周的 PR 管理。SIG Docs 期望所有批准人都参与到此轮值工作中。 更多细节可参见 PR 管理者。

成为批准人

当你满足一定条件时，可以成为一个 SIG Docs 批准人。 来自其他 SIG 的批准人也必须在 SIG Docs 独立申请批准人资格。

申请流程如下：

1. 发起一个 PR，将自己添加到 kubernetes/website 仓库中 OWNERS_ALIASES 文件的对应节区。

   说明：

   如果你不确定要添加到哪个位置，可以将自己添加到 sig-docs-en-owners 中。

2. 将 PR 指派给一个或多个 SIG Docs 批准人。

请求被批准之后，SIG Docs Leads 之一会将你添加到对应的 GitHub 团队。 一旦添加完成，K8s-ci-robot 会在处理未来的 PR 时，将 PR 指派给你或者建议你来评审某 PR。

接下来

• 阅读 PR 管理者，了解所有批准人轮值的角色。

2 - Issue 管理者

除了承担 PR 管理者的职责外， SIG Docs 正式的批准人（Approver）、评审人（Reviewer）和成员（Member） 按周轮流归类仓库的 Issue。

职责

在为期一周的轮值期内，Issue 管理者每天负责：

• 对收到的 Issue 进行日常分类和标记。有关 SIG Docs 如何使用元数据的指导说明， 参阅归类 Issue。
• 密切关注 kubernetes/website 代码仓库中陈旧和过期的 Issue。
• 维护 Issues 看板。

要求

• 必须是 Kubernetes 组织的活跃成员。
• 至少为 Kubernetes 做了 15 个非小微的贡献 （其中某些应是直接针对 kubernetes/website 的贡献）。
• 已经以非正式身份履行该职责。

对管理者有帮助的 Prow 命令

以下是 Issue 管理者的一些常用命令：

# 重新打开 Issue
/reopen

# 将不切合 k/website 的 Issue 转移到其他代码仓库
/transfer[-issue]

# 更改陈旧 Issue 的状态
/remove-lifecycle rotten

# 更改过期 Issue 的状态
/remove-lifecycle stale

# 为 Issue 指派 SIG
/sig <sig_name>

# 添加具体领域
/area <area_name>

# 对新手友好的 Issue
/good-first-issue

# 需要帮助的 Issue
/help wanted

# 将 Issue 标记为某种支持
/kind support

# 接受某个 Issue 的归类
/triage accepted

# 关闭还未处理且未修复的 Issue
/close not-planned

要查找更多 Prow 命令，请参阅命令帮助文档。

何时关闭 Issue

一个开源项目想要成功，良好的 Issue 管理非常关键。 但解决 Issue 也很重要，这样才能维护代码仓库，并与贡献者和用户进行清晰明确的交流。

关闭 Issue 的时机包括：

• 类似的 Issue 被多次报告。你首先需要将其标记为 /triage duplicate； 将其链接到主要 Issue 然后关闭它。还建议将用户引导至最初的 Issue。
• 通过所提供的信息很难理解和解决作者提出的 Issue。 但要鼓励用户提供更多细节，或者在以后可以重现 Issue 时重新打开此 Issue 。
• 相同的功能在其他地方已实现。管理者可以关闭此 Issue 并将用户引导至适当的位置。
• 报告的 Issue 当前未被计划或不符合项目的目标。
• 如果 Issue 看起来是垃圾信息并且明显不相关。
• 如果 Issue 与外部限制或依赖项有关并且超出了本项目的控制范围。

要关闭 Issue，可以在 Issue 中留下一条 /close 的评论。

3 - PR 管理者

SIG Docs 的批准人（Approver） 们每周轮流负责管理仓库的 PR。

本节介绍 PR 管理者的职责。关于如何提供较好的评审意见， 可参阅评审变更。

职责

在为期一周的轮值期内，PR 管理者要：

• 检查悬决的 PR 的质量并确保它们符合样式指南和 内容指南要求。

  • 首先查看最小的 PR（size/XS），然后逐渐扩展到最大的 PR（size/XXL），尽可能多地评审 PR。

• 确保贡献者签署 CLA。
  • 使用此脚本自动提醒尚未签署 CLA 的贡献者签署 CLA。
• 针对变更提供反馈，请求其他 SIG 的成员进行技术审核。
  • 为 PR 所建议的内容更改提供就地反馈。
  • 如果你需要验证内容，请在 PR 上发表评论并要求贡献者提供更多细节。
  • 设置相关的 sig/ 标签。
  • 如果需要，根据文件开头的 reviewers: 块来指派评审人。
  • 你也可以通过在 PR 上作出 @kubernetes/<sig>-pr-reviews 的评论以标记需要某个 SIG 来评审。

• 使用 /approve 评论来批准可以合并的 PR，在 PR 就绪时将其合并。
  • PR 在被合并之前，应该有来自其他成员的 /lgtm 评论。
  • 可以考虑接受那些技术上准确、 但文风上不满足风格指南要求的 PR。 批准变更时，可以登记一个新的 Issue 来解决文档风格问题。 你通常可以将这些风格修复问题标记为 good first issue。
  • 将风格修复事项标记为 good first issue 可以很好地确保向新加入的贡献者分派一些比较简单的任务， 这有助于接纳新的贡献者。

• 同时检查针对参考文档生成器的代码拉取请求， 并对其进行审查（或寻求帮助）。
• 支持问题管理者每日对新问题进行分类和标记。 参见分类和组织问题 了解 SIG Docs 如何使用元数据。

对管理者有用的 GitHub 查询

执行管理操作时，以下查询很有用。完成以下这些查询后，剩余的要评审的 PR 列表通常很小。 这些查询都不包含本地化的 PR，并仅包含主分支上的 PR（除了最后一个查询）。

• 未签署 CLA，不可合并的 PR： 提醒贡献者签署 CLA。如果机器人和评审者都已经提醒他们，请关闭 PR，并提醒他们在签署 CLA 后可以重新提交。

  在作者没有签署 CLA 之前，不要评审他们的 PR！

• 需要 LGTM： 列举需要来自成员的 LGTM 评论的 PR。 如果需要技术审查，请告知机器人所建议的评审者。 如果 PR 继续改进，就地提供更改建议或反馈。

• 已有 LGTM标签，需要 Docs 团队批准： 列举需要 /approve 评论来合并的 PR。

• 快速批阅： 列举针对主分支的、没有明确合并障碍的 PR。 在浏览 PR 时，可以将 "XS" 尺寸标签更改为 "S"、"M"、"L"、"XL"、"XXL"。

• 非主分支的 PR: 如果 PR 针对 dev- 分支，则表示它适用于即将发布的版本。 请添加带有 /assign @<负责人的 github 账号>， 将其指派给发行版本负责人。 如果 PR 是针对旧分支，请帮助 PR 作者确定是否所针对的是最合适的分支。

对管理者有用的 Prow 命令

# 添加 English 标签
/language en

# 如果 PR 包含多个提交（commits），添加 squash 标签
/label tide/merge-method-squash

# 使用 Prow 来为 PR 重设标题（例如一个正在处理 [WIP] 的 PR 或为 PR 提供更好的细节信息）
/retitle [WIP] <TITLE>

何时关闭 PR

审查和批准是缩短和更新我们的 PR 队列的一种方式；另一种方式是关闭 PR。

当以下条件满足时，可以关闭 PR：

• 作者两周内未签署 CLA。 PR 作者可以在签署 CLA 后重新打开 PR，因此这是确保未签署 CLA 的 PR 不会被合并的一种风险较低的方法。

• 作者在两周或更长时间内未回复评论或反馈。

不要害怕关闭 PR。贡献者可以轻松地重新打开并继续工作。 通常，关闭通知会激励作者继续完成其贡献。

要关闭 PR，请在 PR 上输入 /close 评论。

PR 管理者影子计划

2021 下半年，SIG Docs 推出了 PR 管理者影子计划（PR Wrangler Shadow Program）。 该计划旨在帮助新的贡献者们了解 PR 管理流程。

成为一名影子

• 如果你有兴趣成为一名 PR 管理者的影子，请访问 PR 管理者维基页面查看今年的 PR 管理轮值表，然后注册报名。

• 其他人可以通过 #sig-docs Slack 频道申请成为指定 PR 管理者某一周的影子。可以随时咨询（@bradtopol）或某一位 SIG Docs 联席主席/主管。

• 注册成为一名 PR 管理者的影子时， 请你在 Kubernetes Slack 向这名 PR 管理者做一次自我介绍。