kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
website/content/zh/docs/contribute/start.md

37 KiB
Raw Blame History

title slug content_template weight card
开始贡献 start templates/concept 10
name weight
contribute 10

{{% capture overview %}}

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

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

{{% /capture %}}

{{% capture body %}}

关于我们文档的基础知识

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

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

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

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

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

内容指南

SIG Docs 社区创建了有关 Kubernetes 文档中允许哪种内容的指南。查看文档内容指南确定是否允许您要进行的内容贡献。您可以在 #sig-docs 频道中询问有关允许内容的问题。

风格指南

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

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

页面模板

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

Hugo 短代码

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

多语言

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

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

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

提出可操作的 issues

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

如何提出 issue

  • 对于已有页面

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

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

  • 请求创建一个新页面

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

如何记录好的 issues

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

  • 使用 issue 模板，尽可能填写详细的信息。

  • 清楚地描述该 issue 对用户造成的具体影响。

  • 限制 issue 的范围，以提交给合理的工作组。如果问题范围很大，将其拆分成若干个 issues。

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

  • 如果 issue 与另一个 issue 或者拉取请求（PR）有关，您可以通过 issue 的完整 URL 或者 PR 的序号（以 # 为前缀）进行关联。例如 如 #987654。

  • 保持尊重，避免发泄。例如，“关于 X 的文档很差”就是无用且不可执行的反馈。行为准测 也适用于 Kubernetes Github 仓库的交互。

参与 SIG Docs 讨论

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

{{< note >}}

您也可以查看 [Kubernetes 社区会议日历](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles)。

{{< /note >}}

改进现有内容

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

{{< note >}}

**Kubernetes 代码开发者**：如果您在撰写 Kubernetes 新版本的新功能文档，流程会稍有不同。

关于流程指南和最后期限的信息，请参阅编写功能文档。 {{< /note >}}

签署 CNCF CLA

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

开始贡献

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

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

选择使用的 Git 分支

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

  • 用 master 来解决以及发布的内容中的问题，或者对于已经存在的内容进行改进。
  • 使用 release 分支（比如 dev-{{< release-branch >}} 用于 {{< release-branch >}} 发布）来撰写新的特性或者下个版本还未发布的变更说明。
  • 使用 SIG Docs 已经同意的 feature 分支来协作对现有文档进行重大改进或更改，包括内容重组或网站外观的更改。

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

提交 PR

按照如下步骤提交 PR 来改善 Kubernetes 文档。

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

  2. 如果您从未创建过 Kubernetes 文档仓库的 fork，会提示您需要创建。请在您的 Github 账号下创建 fork，而不是在您所在的组织下创建。fork URL 通常是这样的 https://github.com/<username>/website，除非您已经有一个同名的仓库，那样会造成冲突。 您创建 fork 的原因是您无权直接将分支推送到确定的 Kubernetes 仓库。

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

    {{< note >}}

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

{{< /note >}}

<!-- 
Click **Propose file change**. The change is saved as a commit in a
new branch in your fork, which is automatically named something like
`patch-1`. 
-->
点击 **建议修改文件（Propose file change）** 按钮。变更会保存为您 fork 新分支（通常会自动命名为 `patch-1`）中的一个提交内容。

  1. 接下来屏幕会总结您的变更，将您的新分支（head fork 和 compare 选择框）与 base fork 和 base 分支(默认是 kubernetes/website 的 master 分支)进行比较。您可以更改选择框，但现在请不要这么做。看一下屏幕底部显示的变化内容，如果看起来没问题，点击 创建 PR（Create pull request） 按钮。

    {{< note >}}

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

{{< /note >}}

  1. Open a pull request（打开一个 PR） 屏幕出现了。PR 的主题和提交说明的内容一致， 如有需要您也可以修改。主体内容会自动填充您的扩展提交消息（如果存在）和一些模板文本。 阅读模板文本并填写要求的详细信息，然后删除额外的模板文本。 如果在描述中添加 fixes #<000000> 或者 closes #<000000>，其中 #<000000> 是相关问题的编号，则当PR合并时，GitHub 将自动关闭该问题。 保留选中 Allow edits from maintainers（允许维护者编辑） 复选框。 单击 Create pull request（创建拉取请求） 按钮。

    祝贺您！您的 PR 就出现在了[拉取请求](https://github.com/kubernetes/website/pulls) 中。

    几分钟后，您可以预览 PR 所带来的变化。前往您 PR 的 Conversation（对话） 标签页， 点击 deploy/netlify 测试的 Details（详细信息） 链接，它在页面底部附件。 默认会在同一个浏览器窗口中打开。

    {{< note >}}

    请将 PR 请求限制为每种 PR 只能使用一种语言。例如，如果您需要对多种语言的同一代码示例进行相同的更改，请为每种语言打开一个单独的 PR。 
    {{< /note >}}

  1. 等待复审。通常，复审人员会由 k8s-ci-robot 建议指定。如果复审人员建议您修改，您可以 前往 Files changed（改变的文件内容） 标签页，点击任意 PR 中改变的文件页面上的铅笔图标。 保存更改的文件时，将在 PR 监视的分支中创建新的提交。如果您正在等待复审者审核更改， 请每 7 天主动与复审者联系一次。您也可以进入 #sig-docs Slack 频道，这是寻求有关 PR 审查的帮助的好地方。

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

提交案例研究

案例研究强调组织如何使用 Kubernetes 解决实际问题。它们是由 Kubernetes 市场团队共同撰写的，由 {{< glossary_tooltip text="CNCF" term_id="cncf" >}} 进行处理。

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

{{% /capture %}}

{{% capture whatsnext %}}

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

{{% /capture %}}