学习 Kubernetes 基础知识

为 Kubernetes 文档做贡献

Edit This Page

参与 SIG Docs

SIG Docs 是 Kubernetes 项目中的一个 special interest groups， 总的来说，它负责编写、更新和维护 Kubernetes 文档。

SIG Docs 欢迎所有贡献者提供内容和检视。任何人可以提交拉取请求（PR）， 欢迎对文档内容提交 issue 和 对正在进行中的 PR 进行评论。

在 SIG Docs，你可以成为 member、reviewer 或者 approver。 这些角色拥有更高的权限，并且需要承担批准和提交更改的责任。 有关 Kubernetes 社区中的成员如何工作的更多信息，请参见 community-membership。 本文档的其余部分概述了这些角色在 SIG Docs 中发挥作用的一些独特方式， SIG Docs 负责维护 Kubernetes 最面向公众的方面之一 —— Kubernetes 网站和文档。

角色和责任

当一个 pull 请求被合并到用于发布内容的分支(当前为“master”)，该内容将发布并向全世界开放。 为了确保发布内容的质量较高，每个 pull 请求需要 SIG Docs 的 approver 审批。 它是这样工作的。

  • 当某个 pull request 拥有 lgtm 和 approve 标签， 并且没有 hold 标签时，这个 pull request 会自动合入。
  • Kubernetes 组织成员 和 SIG Docs 的 approvers 可以通过评论的方式阻止某个 pull request 自动合入（评论中包含 /hold 或 取消 /lgtm 的内容）。
  • 任何 Kubernetes 成员都可以通过在评论回复 /lgtm 来增加 /lgtm 标签。
  • 只有 SIG Docs 的 approver 可以在评论中回复 /approve 并触发合并。 某些 approver 还兼具其他角色，比如 PR Wrangler 或 SIG Docs chairperson。

关于 Kubernetes 组织成员和 SIG Docs approver 的区别，请参考 Types of contributor。 以下部分将详细介绍这些角色及其内部的工作方式。

Anyone

任何人可以针对 Kubernetes 的任何内容（包括文档）提交 issue。

任何人想到提交 pull request，必须要签署 CLA。 否则 Kubernetes 项目则不能接受你的贡献。

Members

任何 Kubernetes 组织成员 都可以检视 pull request。 SIG Docs 组成员经常需要检视来自其他 SIG 的 pull request，以确保技术上的准确性。

作何 Kubernetes 组织成员都可以在评论中增加 /hold 标签来阻止 PR 被合入。 任何 Kubernetes 组织成员都可以移除 /hold 标签来让PR 合入（必须此前已有 /lgtm 和 /approve 标签）。

成为一个 member

在你成功的提交至少 5 个PR后，你就可以向 Kubernetes 组织提交申请 membership。 按照如下流程：

  1. 找到两个 reviewer 或 approver 为你提名。

    通过 #sig-docs channel on the Kubernetes Slack instance 或者 SIG Docs mailing list 来寻找为你提名的人。

    注意： 不要单独发送邮件给某个人或在 Slack 中私聊。

  2. 在 kubernetes/org 仓库中提交一个 issue 发起请求。 按照指导模板填写请求。

  3. 告知你的提名人，可以通过在 issue 中 @<GitHub-username> 或者直接发送给他们 issue 链接， 这样他们可以过来投票（+1）。

  4. 当请求被批准后，github 管理员团队成员会告诉你批准加入并且关闭 issue：”Congratulations, you are now a member!“。

如果因为某些原因你的申请没有被批准，会员委员会成员会告诉你原因并指导你如何继续申请。

Reviewers

Reviewers 是 @kubernetes/sig-docs-pr-reviews 成员。

Reviewers 负责检视文档的 PR 并提供反馈。

每个 PR 都会自动分配 reviewer，任何贡献者都可以在评论中回复 /assign [@_github_handle] 来请求某个 reviewer 来检视。 如果 reviewer 觉得没有问题且不需要进一步更改时，reviewer 会在评论中回复 /lgtm 。

如果自动分配的 reviewer 未能及时检视，其他的 reviewer 也会参与。 此外，你可以指定某个 reviewer 或者等他们回复 /lgtm。

对于不重要的更改或者非技术性的检视，SIG Docs 的 approver 也可以提供 /lgtm 标签。

如果一个 reviewer 在评论中回复 /approve 会被自动忽略。

关于如何成为 SIG Docs reviewer 以及其责任、时间承诺等更多内容，请参照 Becoming a reviewer or approver。

成为 reviewer

当你满足需求时， 你就可以成为 SIG Docs 的 reviewer。 其他 SIG 的 reviewer 也需要单独向 SIG Docs 申请。

通过提交一个 PR 并把自己加到位于 kubernetes/website 仓库顶层的 top-level OWNERS file 文件中的 reviewers 部分，指定一个或多个当前 SIG Docs 的 approver。

如果你的 PR 被批准，你就成为了 SIG Docs reviewer 了。 K8s-ci-robot 会在接下来的 PR 中请求你检视。

如果您的 PR 被批准，你就会加入 @kubernetes/sig-docs-pr-reviews 组。只有 kubernetes-website-admins 组的成员才可以加入新成员。

Approvers

approver 是 GitHub @kubernetes/sig-docs-maintainers 组织成员。 参考 Teams and groups within SIG Docs。

approver 有权限合入 PR，这意味着他们可以发布内容到 Kubernetes 网站。 如果一个 approver 留下 /approve 评论，则代表他批准了 PR。 如果非 approver 成员尝试批准，则会被自动忽略。

如果某个 PR 已有 /lgtm 标签，approver 再回复一个 /lgtm ，则这个 PR 会自动合入。 SIG Docs approver 应该只在不需要额外的技术检视的情况下才可以标记 /lgtm。

关于如何成为 SIG Docs 的 approver 及其责任和时间承诺等信息，请参考 Becoming a reviewer or approver。

成为 approver

当满足要求 时，你可以成为 SIG Docs 的 approver。其他的 SIG 的 approver 要想成为 SIG Docs 的 approver 需要单独申请。

通过提交一个 PR 并把自己加到位于 kubernetes/website 仓库顶层的 top-level OWNERS file 文件中的 approvers 部分，指定一个或多个当前 SIG Docs 的 approver。

一旦你的 PR 被批准，你就是一个 SIG Docs 的 approver 了。

如果您的 PR 被批准，你就会加入@kubernetes/sig-docs-maintainers 组。只有 kubernetes-website-admins 组的成员才可以加入新成员。

Approver 职责

Approvers 通过查看拉取请求（pr）并将其合并到网站仓库中来完善文档。因为此角色具有其他特权，所以 approvers 还具有其他职责：

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

    粗心的合并会破坏站点，因此请确保在合并某些内容时，您是清楚的。

  • 确保建议的更改符合贡献准则。

    如果您有任何疑问，或者不确定某个问题，请随时联系他人进行审核。

  • 在 /approve PR 之前，请验证 netlify 测试是否通过。

    批准之前必须确保 Netlify 测试通过

  • 请访问 netlify 页面预览 PR，确保批准前一切正常。

PR 协调者

每个 SIG Docs approver 都会参与 PR Wrangler rotation scheduler。 所有 SIG Docs approver 都会参与轮值。 更多信息，请参考做一周的PR协调者。

SIG Docs 主席

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

SIG Docs 团队和自动化

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

GitHub groups

SIG Docs 组定义了两个 GitHub 组：

可以在 GitHub 的评论中 @name 他们来与他们沟通。

这些团队与自动化工具使用的组有所重叠，但并不完全匹配。 对于分配 issue、拉请求和批准 PR，自动化使用来自 OWNERS 文件的信息。

OWNERS 文件和扉页

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

  • blunderbuss
  • approve

这两个插件使用位于 kubernetes/website 仓库顶层的 OWNERS 和 OWNERS_ALIASES 来控制工作流程。

OWNERS 文件包含 SIG Docs reviewer 和 approver 的列表。 OWNERS 文件也可以存在于子目录中中，可以重写 reviewer 和 approver，并且它自动继承上级。 关于 OWNERS 的更多信息，请参考 OWNERS。

此外，一个单独的 Markdown 格式的文件将会列出 reviewer 和 approver（扉页），或者列出 其 GitHub 用户名 或者列出其组名。

结合 OWNERS 文件及扉页可以给 PR 作者提供向谁请求检视的建议。

接下来

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

反馈