学习 Kubernetes 基础知识

为 Kubernetes 文档做贡献

Edit This Page

开始贡献

如果您想要为 Kubernetes 文档做贡献，本页面的内容和链接的主题能够给您帮助。您不必是一位开发者或者技术作者，也同样可以为 Kubernetes 文档及其用户体验带来巨大的影响！您只需要有一个 Github 账号 和一个浏览器。

如果您在寻找有关如何开始向 Kubernetes 仓库贡献代码的信息，请参考 Kubernetes 社区指南。

关于我们文档的基础知识

Kubernetes 文档是以 Markdown 形式编写的，使用 Hugo 进行部署。源码位于 Github 的 https://github.com/kubernetes/website。 大部分文档源码位于 /content/en/docs/。有些参考文档是由 update-imported-docs/ 目录内的脚本自动生产的。

您可以查找 issue、编辑内容或者对其他人的提交内容进行复审，这些都可以在 Github 网站上完成。您也可以使用 Github 内置的历史功能和查询工具。

并非所有的任务都可以通过 Github UI 完成，这些任务会在中级和高级文档贡献指南中讨论。

参与文档特别兴趣小组（SIG Docs）

Kubernetes 文档是由特别兴趣小组（SIG）维护的，该小组名为 SIG Docs。我们通过 Slack 频道、邮件列表和网络视频周会进行交流。 欢迎新的参与者加入。更多信息，请参考参与 SIG Docs。

风格指南

我们维护了一个风格指南页面，上面有关于 SIG Docs 社区对于语法、句法、源格式和排版的约定。 在您做首次贡献前或者在有疑问的时候请先查阅风格指南。

风格的变化是由 SIG Docs 组共同决定的。如您想提交变更或增加内容，请将内容添加到议题并参与会议讨论。 更多信息，参见进阶贡献主题。

页面模板

我们使用页面模板来控制文档页面。需要确保您理解这些模版是如何工作的，请阅读使用页面模板。

Hugo 短代码

Kubernetes 文档使用 Hugo 将 Markdown 转换成 HTML。我们使用标准的 Hugo 短代码，同时也会有部分为 Kubernetes 定制化的代码。 有关如何使用短代码的信息，请参见自定义 Hugo 短代码。

多语言

在 /content/ 目录中有文档源码的多语言版本。每个语言拥有其自己的目录，采用 ISO 639-1 标准 的两位编码命名。例如，英文文档源码位于 /content/en/docs/ 目录。

更多关于对多语言文档做贡献的信息，请参考中级贡献指南中的“本地化内容”。

如果您有兴趣开始一个新的本地化语言项目，请参考“本地化”。

登记文档可操作问题

任何拥有 Github 账号的人都能对于 Kubernetes 文档登记一个问题（或者 bug 报告）。 如果看到有东西坏了，即便您不知道如何修复它，请登记一个问题。 除了您发现微小的错误的情况，例如发现了一个拼写错误，您想自己进行修复。在这种情况下， 您可以修复它，而不用先登记一个 bug。

如何记录问题

如果您在已有的 [Kubernetes 文档](/docs/)页面，在页面底部直接点击 **创建问题** 按钮。
如果您当前未登录 Github，那么请登录。Github 文档表单会带着预填的信息出现。

使用 Markdown 格式，填写尽可能多的详细信息。在方括号 (`[ ]`) 中，使用 `x` 代码选择了该选项。
如果您提交了修复问题的方法，也填在里面。

如果认为有些内容应该存在，但您不知道应该将这些内容存放在哪里，或者任何不适合放在现有页面中，
那么也可以记录一个问题。您可以选择通过内容相近的页面创建问题，或者直接
在 [https://github.com/kubernetes/website/issues/new/](https://github.com/kubernetes/website/issues/new/)
中记录问题。

如何记录好的问题

要确保我们能理解您的问题，并能付诸行动，请谨记如下指南：

例如，“修复安全文档”就是一个不可执行的问题，但 “为'限制网络访问'主题添加详细信息”就是可执行的。

参与 SIG Docs 讨论

SIG Docs 团队的交流采用如下机制：

Note: 您也可以查看 Kubernetes 社区会议日历。

改进现有内容

要改进现有的内容，您可以在创建 fork 之后起草一个 拉取请求（PR） 。 这两个术语是 Github 专用的。 出于本主题的目的，您无需了解有关它们的所有信息，因为您可以通过浏览器做所有的事情。 当您继续阅读贡献者中级指南，您会需要更多 Git 术语的背景知识。

Note: Kubernetes 代码开发者: 如果您在撰写 Kubernetes 新版本的新功能文档，流程会稍有不同。 关于流程指南和最后期限的信息，请参阅编写功能文档。

签署 CLA

在贡献 Kubernetes 的代码或文档前，您 必须 阅读贡献者指南， 并签署贡献者许可协议（CLA）。 别担心 – 不需要太多时间！

找些活干

如果您发现了一些想要马上修复的东西，只需要遵循如下指南。您不需要记录一个问题（尽管你当然可以这么做）。

如果您想从处理现有的问题开始，前往 https://github.com/kubernetes/website/issues 找一些有 good first issue 标签的问题（您可以使用这个 捷径)。 阅读评论，确保针对此问题没有打开的 PR，并且没有人留言说他们最近正在解决这个问题（3天是个很好的规则）。留言说您会去解决这个问题。

选择使用的 Git 分支

提交 PR 最重要的方面就是选择您工作所基于的基础分支。使用如下指南来做决定：

如果您还不确定应该使用哪个分支，在 Slack 上询问 #sig-docs 或者参与 SIG Docs 周会来确认。

提交 PR

按照如下步骤进行 PR 提交以改善 Kubernetes 文档。

  1. 在您发现问题的页面上，点击右上角的铅笔图标。新的页面就会出现，上面会有一些帮助信息。

  2. 如果您从未创建过 Kubernetes 文档仓库的 fork，会提示您需要创建。请在您的 Github 账号 下创建 fork，而不是在您所在的组织下创建。fork URL 通常是这样的 https://github.com/<username>/website， 出发您已经有一个同名的仓库，那样会造成冲突。

  3. Github Markdown 编辑器会载入着文档源码一起出现。根据实际情况撰写变化内容。在编辑器下方， 填写 Propose file change（建议修改文件） 表格。第一个区域需要填写提交说明消息， 不能超过 50 个字符。第二个区域是可选的，也能够填写更多详细信息。

<blockquote class="note">

Note: 不要把 Github 问题或者 PR 的关联信息放在您的提交说明消息中。您可以之后把这些内容添加到 PR 的描述中。

点击 **建议修改文件（Propose file change）** 按钮。
变更会保存为您 fork 新分支（通常会自动命名为 `patch-1`）中的一个提交内容。
  1. 接下来屏幕会总结您的变更，将您的新分支（head fork 和 compare 选择框） 与 base fork 和 base 分支(默认是 kubernetes/website 的 master 分支) 进行比较。您可以更改选择框，但现在请不要这么做。看一下屏幕底部显示的变化内容， 如果看起来没问题，点击 创建 PR（Create pull request） 按钮。
<blockquote class="note">

Note: 如果您现在还不想创建 PR，也可以稍后再做，通过浏览 Kubernetes 网站代码仓库或者您 fork 仓库的网站主页 URL。 Github 网站会检查到您推送了一个新分支到 fork，并提示创建 PR。

  1. Open a pull request（打开一个 PR） 屏幕出现了。PR 的主题和提交说明的内容一致， 如有需要您也可以修改。主体内容会自动填充您的扩展提交消息（如果存在）和一些模板文本。 阅读模板文本并填写要求的详细信息，然后删除额外的模板文本。 保留选中 Allow edits from maintainers（允许维护者编辑） 复选框。 单击 Create pull request（创建拉取请求） 按钮。
祝贺您！您的 PR 就出现在了[拉取请求](https://github.com/kubernetes/website/pulls) 中。

几分钟后，您可以预览 PR 所带来的变化。前往您 PR 的 **Conversation（对话）** 标签页，
点击 `deploy/netlify` 测试的 **Details（详细信息）** 链接，它在页面底部附件。
默认会在同一个浏览器窗口中打开。
  1. 等待复审。通常，复审人员会由 k8s-ci-robot 建议指定。如果复审人员建议您修改，您可以 前往 Files changed（改变的文件内容） 标签页，点击任意 PR 中改变的文件页面上的铅笔图标。 保存更改的文件时，将在 PR 监视的分支中创建新的提交。
  1. 如果修改被接受，复审人员会合并您的 PR，修改就会在几分钟后在 Kubernetes 网站上生效。

这是提交 PR 的唯一方式。如果您已经是一名 Git 和 Github 的高级用户，您也可以使用本地 GUI 或者 Git 命令行。关于使用 Git 客户端的基础会在中级 贡献者指南中讨论。

复审文档 PR

就算不是批注者或者复审者，也同样可以复审 PR。复审人员并不是”固定”的，意味着您单独的评审并不会让 PR 合并。 然而，这依然对我们是很有帮助的。即使您没有留下任何评审意见，您可以了解 PR 的规范和礼仪，并习惯工作流程。

  1. 前往 https://github.com/kubernetes/website/pulls。 请会看到一个列表，里面包含了所有对于 Kubernetes 网站和文档提的 PR。
  1. 默认情况下，使用的筛选器是 open，所以您不会看见已经关闭或合并的 PR。 最好使用 cncf-cla: yes 筛选器，并且对于第一次复审来说，最好加上 size/S 或者 size/XS。size 标签会根据 PR 修改的代码行数自动生成。 您可以通过页面顶端的选择框应用筛选器，或者使用 这个捷径 来查找所有小型 PR。所有筛选条件都是 与 的，所以您不能在一次查询中同时查找 size/XS 和 size/S 的结果。

  1. 前往 Files changed（文件修改） 标签页。查看 PR 中的变化部分，如果适用，也看一下关联的问题。 如果您发现问题或者可以改进的空间，将鼠标悬浮在那一行并点击前面出现的 + 加号。

    你可以留下评论，选择 Add single comment（仅添加评论） 或者也可以 Start a review（开始复审）。 典型来说，开始复审更好，因为这样您就可以在多行下留下评论，并且只有在完成复审后统一提交并通知 PR 的作者， 而不是每一条评论都发送通知。

  1. 完成后，点击页面顶端但 Review changes（复审修改） 按钮。您可以总结复审，并且可以选择 comment（评论），approve（批准），或者 request changes（请求变更）。 新的贡献者应该选择 Comment（评论）。

感谢您对于 PR 的复审工作！当您对于项目还是新人时，最好在拉取请求评论中征求反馈意见。 Slack 的 #sig-docs 频道就是一个征求意见好去处。

撰写一篇博客文章

任何人都可以撰写博客并提交复审。博客文章不应具有商业性质，而应包含广泛适用于 Kubernetes 社区的内容。

要提交博客文章，您可以选择使用 Kubernetes 博客提交表单 或者按如下步骤进行：

  1. 签署 CLA，如果您还未签署的话。
  2. 查看现有博客文章的 Markdown 格式，位于网站代码仓库。
  3. 在您选择的文本编辑器中写下您的博客文章。
  4. 在步骤 2 的相同链接中，点击 Create new file（创建新文件） 按钮。 将您的内容粘贴到编辑器中。将文件命名为与博客文章的标题的名称， 但不要将日期放在文件名中。博客复审人员将与您一起确定最终文件名和博客发布日期。
  5. 保存文件时，Github 将引导您完成 PR 过程。
  6. 博客复审人员会对您提交对内容进行复审，并与您一起完成反馈意见和最终的详细信息。 博客文章获得批准后，博客将会安排时间进行发布。

提交一个案例研究

案例研究强调组织如何使用 Kubernetes 解决实际问题。它们是由 Kubernetes 市场团队共同撰写的，由 CNCF 进行处理。

看一下现有案例研究的源码。 使用 Kubernetes 案例研究提交表提交您的提案。

接下来

当您对本主题中讨论的所有任务感到满意，并且您希望以更深入的方式与 Kubernetes 文档团队合作， 请阅读中级贡献者指南。

反馈