参与 SIG Docs

SIG Docs 是 Kubernetes 项目 特别兴趣小组 中的一个，负责编写、更新和维护 Kubernetes 的总体文档。 参见社区 GitHub 仓库中 SIG Docs 以进一步了解该 SIG。

SIG Docs 欢迎所有贡献者提供内容和审阅。任何人可以提交拉取请求（PR）。 欢迎所有人对文档内容创建 Issue 和对正在处理中的 PR 进行评论。

你也可以成为成员（member）、 评阅人（reviewer） 或者 批准人（approver）。 这些角色拥有更高的权限，且需要承担批准和提交变更的责任。 有关 Kubernetes 社区中的成员如何工作的更多信息，请参见 社区成员身份。

本文档的其余部分概述了这些角色在 SIG Docs 中发挥作用的一些独特方式。 SIG Docs 负责维护 Kubernetes 最面向公众的方面之一 —— Kubernetes 网站和文档。

SIG Docs 主席

每个 SIG，包括 SIG Docs，都会选出一位或多位成员作为主席。 主席会成为 SIG Docs 和其他 Kubernetes 组织的联络接口人。 他们需要了解整个 Kubernetes 项目的架构，并明白 SIG Docs 如何在其中运作。 如需查询当前的主席名单，请查阅 领导人员。

SIG Docs 团队和自动化

SIG 文档中的自动化服务依赖于两种不同的机制: GitHub 团队和 OWNERS 文件。

GitHub 团队

GitHub 上有两类 SIG Docs 团队：

可以在 GitHub 的评论中使用团队的名称 @name 来与团队成员沟通。

有时候 Prow 所定义的团队和 GitHub 团队有所重叠，并不完全一致。 对于指派 Issue、PR 和批准 PR，自动化工具使用来自 OWNERS 文件的信息。

OWNERS 文件和扉页

Kubernetes 项目使用名为 prow 的自动化工具来自动处理 GitHub issue 和 PR。 Kubernetes website 仓库 使用了两个 prow 插件：

这两个插件使用位于 kubernetes/website 仓库顶层的 OWNERS 文件和 OWNERS_ALIASES 文件来控制 prow 在仓库范围的工作方式。

OWNERS 文件包含 SIG Docs 评阅人和批准人的列表。 OWNERS 文件也可以存在于子目录中，可以在子目录层级重新设置哪些人可以作为评阅人和 批准人，并将这一设定传递到下层子目录。 关于 OWNERS 的更多信息，请参考 OWNERS 文档。

此外，每个独立的 Markdown 文件都可以在其前言部分列出评阅人和批准人， 每一项可以是 GitHub 用户名，也可以是 GitHub 组名。

结合 OWNERS 文件及 Markdown 文件的前言信息，自动化系统可以给 PR 作者可以就应该 向谁请求技术和文字评阅给出建议。

PR 是怎样被合并的

当某个拉取请求（PR）被合并到用来发布内容的分支，对应的内容就会被发布到 https://kubernetes.io。 为了确保我们所发布的内容的质量足够好，合并 PR 的权限仅限于 SIG Docs 批准人。下面是合并的工作机制：

接下来

关于贡献 Kubernetes 文档的更多信息，请参考：

1 - 角色与责任

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

任何人（Anyone）

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

任何人都可以：

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

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

成员（Members）

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

成员可以：

成为一个成员

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

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

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

    说明：

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

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

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

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

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

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

    说明：

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

评审人（Reviewers）

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

评审人可以：

你可以是 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 团队的成员。

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

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

批准 PR

只有批准人和 SIG Docs Leads 可以将 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。

接下来

2 - Issue 管理者

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

职责

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

要求

对管理者有帮助的 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，可以在 Issue 中留下一条 /close 的评论。

3 - PR 管理者

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

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

职责

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

说明：

PR 管理者的职责不适用于本地化 PR（非英语 PR）。 本地化团队有自己的流程和团队来审查其语言 PR。 但是，其对于确保被语言 PR 被正确标记，审查与语言无关的小型 PR（如链接更新），或为长期搁置的 PR（已打开超过 6 个月且一个月或更长时间未更新的）添加审阅者或贡献者标签通常很有帮助。

对管理者有用的 GitHub 查询

执行管理操作时，以下查询很有用。完成以下这些查询后，剩余的要评审的 PR 列表通常很小。 这些查询都不包含本地化的 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：

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

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

说明：

一个名为 k8s-ci-robot 的自动服务会在 Issue 停滞 90 天后自动将其标记为过期；然后再等 30 天，如果仍然无人过问，则将其关闭。 PR 管理者应该在 Issue 处于无人过问状态 14-30 天后关闭它们。

PR 管理者影子计划

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

成为一名影子