学习 Kubernetes 基础知识

为 Kubernetes 文档做贡献

Edit This Page

中级贡献

本文假定你已经阅读并掌握了开始贡献中介绍的内容， 想要了解更多关于贡献的内容。

Note: 有些任务需要使用Git命令行客户端和其他工具。

现在，您已经熟悉了Kubernetes文档，并按照开始贡献文章中介绍的方式进行了贡献， 您可能已经准备好做更多的工作。这些任务假设您已经或愿意获得以下主题领域的更深入的知识:

这些任务不像初学者的任务那样是顺序的。没有人期望一个人会一直做所有的事情。

评审 pull request

通常，每周都会有一个特定的文档审核志愿者对pull requests 和 issues 进行分类和审核。这个人就是本周的“PR 牧马人”。排班计划在PR 牧马人排班维护。 如果想要加入排班计划，需要参加每周的 SIG Docs 会议并志愿申请。 尽管你不在本周的排班计划中，你也可以审核那些还未开始检视的PR。

除了轮换之外，自动化系统（机器人）会根据修改的文件自动推荐相应的 approver 和 reviewer。 PR作者应该遵循机器人的指导，这也有助于PR得到快速审查。

我们希望尽快合并和发布pull requests。 为了确保文档是准确的和最新的，每个PR都需要由理解内容的人以及具有编写优秀文档经验的人来评审。

评审人员和批准人员需要提供可操作的和建设性的反馈，以保持贡献者的参与并帮助他们改进。 有时候，帮助一个新的贡献者把他们的PR准备好合并比你自己重写它需要更多的时间， 但是从长远来看，当我们有不同的积极参与者时，这个项目会更好。

在开始评审PR之前，请确保熟悉 文档风格指南 和 行为准则。

找一个PR来评审

要查看所有打开的PR，请转到GitHub仓库中的Pull Requests选项卡。 当符合以下所有条件时，PR才有资格进行评审：

如果PR不符合合并的条件，请留下评论，让作者知道问题所在，并帮助他们解决问题。 如果他们被告知并在几周或几个月内没有解决问题，最终他们的PR将被关闭而不会合并。

如果您是新手，或者您没有太多的带宽，请寻找具有 size/XS 或 size/S 标记集的PR。 大小由PR更改的行数自动设置。

评审人员和批准人员

Kubernetes 网站仓库与 Kubernetes 的一些代码仓库在涉及审核者和审批者角色时的操作方式不同。 有关评审人员和批准人员职责的更多信息，请参见参与。 这里只做一个概述。

如果PR拥有来自Kubernetes社区的任何人的/lgtm评论和来自sig-docs-maintainers组的/approved评论， 只要它没有被hold并且作者已签署了CLA，PR就会被合并。

审核PR

  1. 阅读PR描述，并阅读任何附加的问题或链接，如果有的话。 “快速评审”有时弊大于利，所以确保你有正确的知识来提供有意义的评审。

  2. 如果其他人是审核这个PR的最佳人选，请通过添加/assign @<github-username>的评论让他们知道。 如果你要求一个非文档人员进行技术评审，但仍然想从文档的角度来评审PR，那就继续吧。

  3. 转到 Files changed 选项卡。查看所有的修改行。删除的内容具有红色背景，这些行也以 - 符号开头。 添加的内容具有绿色背景，这些行也以 + 符号开始。在一行中，实际修改的内容的背景颜色比该行的其余部分略深一些。

    • 特别是如果PR使用复杂的格式或更改CSS、Javascript或其他站点范围内的元素，您可以使用PR预览网站。 转到 Conversation 选项卡，单击页面底部附近的 deploy/netlify 测试的 Details 链接。 默认情况下，它会在同一个浏览器窗口中打开，所以在一个新窗口中打开它，这样你就不会丢失你的部分评论。 切换回 Files changed 选项卡以继续您的审阅。
    • 确保PR符合文档风格指南， 如果不符合，请将作者链接到风格指南的相关部分。

    • 如果您对给定的更改有疑问、评论或其他反馈，请将鼠标悬停在一行上，然后单击出现的蓝白相间的 + 号。 键入您的评论并单击 Start a review。

    • 如果你有更多的评论，请以同样的方式留下评论。

    • 按照惯例，如果您看到一个与PR的主要目的无关的小问题，比如一个打印错误或空格错误， 您可以将它指出来，并在注释前加上nit:以便作者知道您认为它是无关紧要的。 他们仍然应该解决这个问题。

    • 当您查看完所有内容，或者没有任何评论时，回到页面顶部并单击 Review changes。 选择Comment 或Request Changes。添加评审摘要， 并在评审摘要字段中另起一行添加适当的Prow 命令。 SIG Docs 遵循Kubernetes代码审查流程。 您所有的意见将在一个单一的评论中发送给PR作者。

      • 如果您认为PR已经准备好合并，请将文本 /approve 添加到摘要中。
      • 如果PR不需要额外的技术审查，也可以同时添加文本 /lgtm 。
      • 如果PR 确实 需要额外的技术审查，使用 /assign + GitHub 用户名添加需要提供技术审查的人。 查看上面出现的 Markdown 文件中的reviewers字段，看看谁可以提供技术审阅。
      • 如果需要阻止PR被合并，加上 /hold ，就会设置 do-not-merge/hold 标签。
      • 如果PR没有冲突、有 lgtm 和 approved 标签且没有 hold 标签，它就会自动合并。

      • 如果PR拥有 lgtm 和 approved 后再有新的变更，那么这些标签会自动清除。

        PR中可能用到的命令，参阅 斜线命令列表。

    • 如果您以前选择了Request changes ，并且PR作者已经处理了您的关注点， 那么您可以在Files changed 选项卡或 Conversation 选项卡底部更改您的审阅状态。 确保添加 /approve 标签，并在必要时指派技术审阅人员，以便合并PR。

提交到别人的PR

留下评论是有帮助的，但有时你需要把自己的想法融入到其他人的PR中，而不仅仅是留下评论。

除非对方明确要求你“接手”，或者你想重新建立一个长期被抛弃的PR，否则不要急于“接手”。 虽然短期内这样做可能更快，但会剥夺这个人做出贡献的机会。

您的做法（接手）取决于您是需要编辑已经在PR范围内的文件，还是PR尚未触及的文件。

如果以下任何一件事是符合的，你就不能提交到某人的PR:

文件已在PR中修改

这个方法使用GitHub UI。如果您愿意，您可以使用命令行，即使您想更改的文件是PR的一部分，如果您更愿意这样工作的话。

  1. 点击 Files changed 选项卡。
  2. 向下找到你想要编辑的文件，点击铅笔图标。
  3. 修改并在下面添加提交记录，点击 Commit changes。

您的提交现在被推送到PR对应的分支(可能在作者的分支上)， 在PR中，您的更改反映在 Files changed 选项卡中。 留下评论，让PR作者知道你修改了PR。

如果作者使用命令行而不是GitHub UI来处理这个PR，那么在处理PR之前， 他们需要获取fork的更改并将本地分支重新建立在fork中的分支上。

如果文件没有被PR修改

如果需要更改尚未包含在PR中的文件，则需要使用命令行。 如果您喜欢使用这个方法而不喜欢使用GitHub UI，那么您总是可以使用这个方法。

  1. 获取作者的fork的URL。你可以在Conversation 标签的底部找到它。 查找文本 Add more commits by pushing to 。 这个短语后面的第一个链接是到分支的，第二个链接是到fork的。 复制第二个链接。稍后会用到分支的名称。

  2. 要给远程设置一个名称(比如作者的GitHub用户名)，然后使用以下语法添加远程：

      git remote add <name> <url-of-fork>

  3. 获取远程。这不会更改任何本地文件，但会更新克隆的远程对象的概念(如分支和标记)及其当前状态。

      git remote fetch <name>

  4. 拉取远程分支。如果已经有同名的本地分支，则此命令将失败。

    git checkout <branch-from-PR>

  5. 进行更改，使用 git add 添加更改，然后提交更改。

  6. 将您的更改推到作者的远程。

      git push <remote-name> <branch-name>

  7. 回到GitHub UI并刷新PR。给PR作者留言，让他们知道你修改了PR。

如果作者使用命令行而不是GitHub UI来处理这个PR，那么在处理PR之前， 他们需要获取fork的更改并将本地分支重新建立在fork中的分支上。

使用本地克隆

对于需要多个文件的更改，或者涉及创建新文件或移动文件的更改， 使用本地Git克隆比依赖GitHub UI更有意义。 这些指令使用git命令，并假设您已经在本地安装了它。 您可以将它们调整为使用本地图形化Git客户机。

克隆仓库

对于处理Kubernetes文档的每个物理机，只需要克隆存储库一次。

  1. 在终端中使用 git clone 来克隆仓库。你不需要指定任何证书。

      git clone https://github.com/kubernetes/website

    新目录 website 会在当前目录中创建并包含该仓库的内容。

  2. 进入 website 目录，将默认的 origin 重命名为远端 upstream。

      cd website

  git remote rename origin upstream

  3. 如果还没有这样做，请在GitHub上创建存储库的分支。 在您的web浏览器中，访问https://github.com/kubernetes/website 并单击Fork按钮。几秒钟后，您将被重定向到您的fork的URL，它通常类似于https://github.com/<username>/website ， 除非您已经有一个名为 website的存储库。复制这个网址。

  4. 在你的fork中增加另一个远端 origin:

      git remote add origin <FORK-URL>

使用本地仓库

在本地存储库上启动新的工作单元之前，您需要确定将工作基于哪个分支。 答案取决于你在做什么，但是下面的指导方针是适用的：

更多指导，请参考选择分支。

在您决定要使用哪个分支之后(或者用Git术语来说，基于它)， 使用以下工作流来确保您的工作基于该分支的最新版本。

  1. 拉取 upstream 和 origin 远端。 这将更新您对这些分支所包含内容的本地概念，但不会更改您的本地分支。

      git fetch upstream
  git fetch origin

  2. 基于你选择的分支创建一个新的跟踪分支。以你使用master为例：

      git checkout -b <my_new_branch> upstream/master

    新分支基于 upstream/master, 而不是你本地的 master。它跟踪 upstream/master。

  3. 在检出的分支上使用编辑器修改。 你可以随时使用 git status 命令来查看你的更改。

  4. 当您准备提交pull request时，提交您的更改。 首先使用git status查看需要向变更集中添加哪些更改。 有两个重要的部分:Changes staged for commit和Changes not staged for commit。 如果您希望将后一节中显示的modified 或 untracked 文件添加到提交中，你需要使用git add。

      git add example-file.md

    当所有文件准备好时，使用 git commit 命令提交：

      git commit -m "Your commit message"

    Note: 不要在提交消息中引用GitHub issue 或 PR(通过ID或URL)。如果您这样做了，那么每当提交出现在新的Git分支中时，就会导致该issue或PR获得通知。稍后，您可以在GitHub UI中链接问题并将请求拉到一起。

  5. 您还可以选择使用hugo命令在本地暂存站点来测试您的更改。时间看本地更改。 您还可以在提交PR后查看更改。

  6. 在创建包含本地提交的PR之前，需要将分支推到fork，也就是origin端点。

      git push origin <my_new_branch>

    从技术上讲，您可以从push命令中省略分支名称，但是这种情况下的行为取决于您使用的Git版本。 如果包含分支名称，结果将更加可重复。

  7. 此时，如果您在web浏览器中访问https://github.com/kubernetes/website, GitHub会检测到您将一个新的分支推送到您的fork，并提供创建一个pull请求。填写pull request模板。

    • 标题不应超过50个字符，并总结更改的意图。
    • 长表单描述应该包含关于修复的更多信息，如果PR修复了GitHub issue， 则应该包含类似Fixes #12345这样的行。 这将导致在合并PR时自动关闭该问题。
    • 您可以添加标签或其他元数据并分配审阅人员。有关语法，请参见分类和分类问题。

    点击 Create pull request

  8. 几个自动化测试将运行与您所应用的更改的网站状态。 如果任何测试失败，请单击Details链接获取更多信息。 如果Netlify测试成功完成，它的Details链接将转到Kubernetes网站的阶段性版本， 其中应用了您的更改。 这是审阅人员检查更改的方式。

  9. 如果您注意到需要进行更多的更改，或者评审人员给了您反馈，请在本地处理反馈， 然后再次重复步骤4 - 6，创建一个新的提交。新的提交被添加到您的pull请求中， 测试再次运行，包括Netlify。

  10. 如果审查员将更改添加到您的pull请求中，您需要从fork获取这些更改，然后才能添加更多的更改。 假设您的分支当前已签出，请使用以下命令来完成此操作。

      git fetch origin
  git rebase origin/<your-branch-name>

    在rebasing之后，您需要添加-f标志来强制推送分支。

      git push -f origin <your-branch-name>

  11. 如果其他人的更改合并到您工作所基于的分支中，并且您对相同文件的相同部分进行了更改， 则可能会发生冲突。如果pull请求显示有需要解决的冲突，您可以使用GitHub UI解决它们， 或者在本地解决它们。

    首先执行第10步，确保你的fork仓库与你本地分支一致。

    接着，拉取 upstream 并 rebase 你的分支。

      git fetch upstream
  git rebase upstream/master

    如果存在Git无法自动解决的冲突，可以使用git status命令查看冲突文件。 对于每个冲突文件，编辑它并查找冲突标记>>>，<<<，and ===。 解决冲突并删除冲突标记。然后使用git add <filename>， 并使用git rebase --continue继续将更改添加到更改集中。 当所有提交都已应用，并且没有更多冲突时，git status将显示您不在rebase中， 并且不需要提交任何更改。此时，强制将分支推到fork, pull请求应该不再显示任何冲突。

如果您在解决冲突方面遇到困难，或者您被与pull请求相关的任何其他事情卡住， 请在#sig-docs Slack通道或kubernet-sig-docs邮件列表中寻求帮助。

本地查看更改

如果您还没有准备好创建一个pull请求， 但是您希望看到您的更改是什么样子的， 那么您可以构建并运行一个docker映像来生成所有文档并在本地提供它。

  1. 本地构建镜像:

      make docker-image

  2. kubernetes-hugo 镜像构建完成后，可以构建并启动网站：

      make docker-serve

  3. 在浏览器地址栏输入 localhost:1313。Hugo将监视文件系统的更改，并根据需要重新构建站点。

  4. 如果想停掉本地Hugo实例，只需要在命令行中键入Ctrl+C来关闭命令行窗口。

或者，您可以在您的开发机器上安装并使用hugo命令：

  1. 安装 Hugo 版本 或更新版本.

  2. 在终端中，转到您克隆的Kubernetes文档的根目录，并输入以下命令：

      hugo server

  3. 在浏览器地址栏中输入 localhost:1313。

  4. 如果想停掉本地Hugo实例，只需要在命令行中键入Ctrl+C来关闭命令行窗口。

问题归类

在任何给定的一周内，一个特定的文档审批者会自愿对pull请求和问题进行初步分类和审查。 要进入这个名单，参加每周的团体文档会议和志愿者。 即使你不在这周的时间表上，你仍然可以审核PR。

SIG文档人员只负责对文档问题进行分类和分类。一般的网站问题也归档在kubernetes/website 资源库中。

当你对一个问题进行分类时：

如果你针对问题分类有疑问，请在Slack #sig-docs 频道或 kubernetes-sig-docs 邮件列表 中询问。

有关标签的更多信息

这些准则并非一成不变，可能会发生变化。

优先级

问题的优先级会影响问题的解决速度。对于文档，以下是设置问题优先级的准则：

P1

P2

P3

处理特殊问题类型

我们经常遇到以下类型的问题，有必要记录如何处理它们。

重复的问题

如果单个问题可以解决一个或多个问题，则应将该问题合并为一个问题。 您应该决定哪个问题保持打开状态（或打开一个新问题），移植所有相关信息，链接相关问题， 并关闭描述同一问题的所有其他问题。只处理一个问题将有助于减少混乱并避免重复处理同一问题。

无效链接问题

根据报告无效链接的位置，需要采取不同的措施来解决此问题。 API和Kubectl文档中的无效链接是自动化问题，应分配为P1，直到可以完全解决该问题为止。 所有其他无效链接都是需要手动修复的问题，可以将其分配为P3。

博客问题

随着时间的流逝，Kubernetes博客条目预计会过时， 因此我们仅保留不到一年的博客条目。 如果某个问题与存在超过一年的博客条目有关，则应将其关闭而不进行修复。

支持请求或代码错误报告

相反，为文档带来的一些问题是底层代码的问题， 或者在某些内容（例如教程）不起作用时请求帮助。 对于与文档无关的问题，请关闭issue并指示请求者正确的支持场所（Slack，Stack Overflow）， 并在适当的地方针对具有功能缺陷的问题提出问题（可以从kubernetes/kubernetes开始）。

对支持请求的响应示例：

This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](http://slack.k8s.io/). You can also search
resources like
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.

You can also open issues for Kubernetes functionality in
 https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

示例代码错误报告响应：

This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

记录新功能

每个主要的Kubernetes版本都包含新功能，其中许多功能至少需要少量文档才能向人们展示如何使用它们。

通常，负责功能的SIG负责对kubernetes/website存储库的相应release分支发起PR， 提交该功能的文档草稿 ，并且由SIG Docs团队中的某人提供编辑反馈或直接编辑草稿。

要了解即将发布的功能，请参加每周一次的sig-release会议 （请参阅社区页面以获取即将举行的会议， 并在kubernetes/sig-release 存储库中监视特定于发行版的文档。 每个发行版在/sig-release/tree/master/releases/ 目录下都有一个子目录。每个子目录包含一个发布计划，一个发布说明草稿以及一个列出发布团队中每个人的文档。

功能跟踪表

给定Kubernetes版本的功能跟踪表 列出了计划发布的每个功能。 每个订单项都包含功能名称，功能主要GitHub问题的链接，其稳定性级别（Alpha，Beta或Stable）， SIG和负责实施此功能的人员，是否需要文档，发布说明草稿功能，以及是否已合并。请记住以下几点：

记录功能

如上所述，新功能的草案内容通常由负责实施新功能的SIG提交。 这意味着您的角色可能更像是给定功能的牧羊人角色。

选择要记录/跟踪的功能后，请在 #sig-docs Slack频道， 每周一次的sig-docs会议中或直接在功能SIG提交的PR上询问有关功能。 如果得到批准，则可以使用提交到别人的PR 中介绍的技术来编辑 PR。

如果您需要编写新主题，则以下链接很有用：

SIG成员记录了新功能

如果您是Kubernetes开发新功能的SIG成员，则需要一并更新SIG文档， 以确保在发布该功能时及时记录了您的功能。 查看 功能跟踪电子表格， 或在 #sig-release Slack频道中查看验证计划详细信息和截止日期。 与文档相关的一些截止日期是：

如果您的功能是Alpha功能并且由功能开关 控制，请确保将其作为PR的一部分添加到功能开关。 如果您的功能要移出Alpha，请确保将其从该文件中删除。

贡献其他仓库

该Kubernetes项目包含超过50个仓库。 这些存储库中许多都包含可以视为文档的代码或内容，例如面向用户的帮助文本，错误消息， API参考中的面向用户的文本，甚至是代码注释。

如果您看到文本并且不确定其来源，则可以在Kubernetes组织级别使用GitHub的搜索工具在所有存储库中搜索该文本。 这可以帮助您确定将问题或PR提交到哪里。

每个存储库可能都有自己的流程和过程。 在您提交的问题或提交PR，查看存储库的README.md，CONTRIBUTING.md以及 code-of-conduct.md。

大多数存储库使用issue和PR模板。 浏览一些未解决的问题和PR，以了解该团队的流程。 提交问题或PR时，​​请确保尽可能详细地填写模板。

本地化内容

Kubernetes文档首先是用英语编写的，但是我们希望人们能够使用他们选择的语言来阅读它。 如果您愿意用另一种语言编写，尤其是在软件领域，则可以帮助本地化Kubernetes文档 或提供有关现有本地化内容的反馈。 请参阅本地化 ， 并在[kubernetes-sig-docs邮件列表]kubernetes-sig-docs mailing list #sig-docs上询问，或者在Slack上询问是否有帮助的兴趣。

参与本地化工作

请遵循以下准则来使用本地化内容：

接下来

如果您熟悉本主题中讨论的所有任务，并且想与Kubernetes文档小组进行更深入的接触， 请阅读高级文档贡献者主题。

反馈