为 Kubernetes 文档做贡献

Kubernetes v1.16 版本的文档已不再维护。您现在看到的版本来自于一份静态的快照。如需查阅最新文档,请点击 最新版本。

Edit This Page

中级贡献

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

注意:

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

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

  • Kubernetes 概念
  • Kubernetes 文档工作流程
  • 在哪里和如何找到即将推出的 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 才有资格进行评审:

  • 拥有 cncf-cla:yes 标签
  • 描述中没有 WIP
  • 没有包含 do-not-merge 字样的标签
  • 没有合并冲突
  • 基于正确的分支(通常为 “master”,除非 PR 与某个未发布的功能相关)
  • 没有被其他文档人员(或其他技术领域的评审人)评审,除非你被显式的请求参与评审。 需要说明的是,如果其他评审已经结束的情况下,你再留下很多新的意见,会让人感到沮丧,这适得其反。

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

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

Reviewers and approvers

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

  • 当评审人员以评审 PR 的技术准确性时,评审人员发表一个 /lgtm 评论表示技术上是无误的。

    注意: 如果你对技术准确性不确信,不要在涉及文档修改的 PR 中回复 /lgtm
  • 批准者审核有关文档修改的内容时,注重质量和相关规范(比如风格规范)。 只有在 OWNERS 文件中列出的 人才可以批准 PR。批准 PR 时,需要回复一个 /approve 评论。

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

注意:

“参与”部分包含有关 reviewers 和 approvers 的更多信息,包括 approvers 的具体职责。

审核 PR

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

  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。 选择CommentRequest Changes。添加评审摘要, 并在评审摘要字段中另起一行添加适当的 Prow 命令。 SIG Docs 遵循 Kubernetes 代码审查流程。 您所有的意见将在一个单一的评论中发送给 PR 作者。

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

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

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

提交到别人的 PR

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

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

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

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

  • 如果 PR 作者将他们的分支直接推入 https://github.com/kubernetes/website/ 仓库,那么只有具有 push 访问权限的审阅者才能提交到他们的 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>
    

使用本地仓库

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

  • 对于现有内容的一般改进,可以从 master 开始。
  • 对于关于 Kubernetes 发布版本中已经存在的特性的新内容,请从 master 开始。
  • 对于多个 SIG Docs 贡献者将协作的长期工作,例如内容重组,使用为该工作创建的特定功能分支。
  • 对于与即将发布但尚未发布的 Kubernetes 版本相关的新内容,请使用为该 Kubernetes 版本创建的预发布特性分支。

更多指导,请参考选择分支

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

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

      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 commitChanges not staged for commit。 如果您希望将后一节中显示的 modifieduntracked 文件添加到提交中,你需要使用 git add

      git add example-file.md
    

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

      git commit -m "Your commit message"
    

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

  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 时自动关闭该 issue。
    • 您可以添加标签或其他元数据并分配审阅人员。有关语法,请参见分类 issues

    点击 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 版本 0.59.1 或更新版本.

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

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

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

issues 归类

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

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

当你对一个 issue 进行分类时:

  • 评估这个 issue 是否有价值。有些 issues 可以通过回答问题或向作者指出资源来迅速解决。
  • 如果 issue 没有足够的细节可以采取行动,或者模板没有填好,询问作者更多的信息。
  • 向 issue 添加标签(有时称为标签)、项目或者里程碑。SIG 文档团队并没有大量使用项目和里程碑。
  • 根据您的判断,对某个 issue 拥有所有权并为其提交 PR (特别是如果它是快速的或与您已经在做的工作相关的)。

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

有关标签的更多信息

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

  • 一个 issue 可以有多个标签。
  • 一些标签使用斜杠符号进行分组,可以将其视为“子标签”。例如,sig/ 存在许多标签,例如 sig/clisig/api-machinery
  • 系统会根据 issue 所涉及文件中的元数据,issue 注释中使用的斜杠命令或 issue 文本中的信息,自动添加一些标签。
  • 由负责 issue 分类的人员(或报告 issue 的人员,如果他们是 SIG 文档批准者)手动添加一些标签。
    • Actionable:似乎有足够的信息可以解决或解决此 issue。
    • good first issue: Kubernetes 或 SIG Docs 经验有限的人也有可能可以解决此 issue。
    • kind/bugkind/featurekind/documentation: 如果提出 issue 的人未正确填写模板,则可能不会自动分配这些标签。 错误是现有内容或功能的 issue,功能是对新内容或功能的请求。kind/documentation 标签当前未使用。
    • 优先级标签:定义 issue 的相对严重性。 如 Kubernetes 贡献者指导 中所述。
  • 要添加标签,添加 /label <label-to-add>。标签必须已经存在。 如果您尝试添加不存在的标签,该命令将被默认忽略。

处理特殊 issue 类型

我们经常遇到以下类型的 issues,足以记录如何处理它们。

重复的 issues

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

无效链接 issues

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

博客 issues

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

支持请求或代码错误报告

相反,为文档带来的一些 issues 是底层代码的 issues, 或者在某些内容(例如教程)不起作用时请求帮助。 对于与文档无关的 issues,请关闭 issue 并指示请求者正确的支持场所(Slack,Stack Overflow), 并在适当的地方针对具有功能缺陷的问题提出 issue(可以从 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/ 目录下都有一个子目录。每个子目录包含一个发布计划,一个发布说明草稿以及一个列出发布团队中每个人的文档。

  • 发布时间表包含与发布有关的所有其他文档、会议、会议记录和里程碑的链接。 它还包含有关该发行版的目标和时间表的信息,以及此发行版的任何特殊流程。 在文档底部附近,定义了几个与发布相关的术语。

    本文档还包含Feature tracking sheet的链接,这是查找排定要发布的所有新功能的正式方法。

  • 发布团队文档列出了负责每个发布角色的人员。 如果不清楚要与谁谈论某个特定功能或问题,请参加发布会议询问您的问题, 或者与发布负责人联系,以便他们可以重定向您。

  • 发行说明草稿是了解更多有关特定功能、更改、不推荐使用以及更多有关发行版本的好地方。 该内容要到发布周期的后期才能最终确定,因此请谨慎使用。

功能跟踪表

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

  • Beta 和稳定功能通常比 Alpha 功能具有更高的文档优先级。
  • 很难测试(因此要文档记录)尚未合并的功能,或者至少在其 PR 中被认为功能完整的功能。
  • 确定某个功能是否需要文档是一个手动过程,并且仅仅因为某个功能未标记为需要文档并不意味着它就不需要它们。

记录功能

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

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

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

SIG 成员记录了新功能

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

  • 文档截止期限 - 打开占位 PR :针对 kubernetes/website 仓库中的 release-X.Y 分支提交一个 PR, 稍作修改(占位),稍后您将继续修改。使用 Prow 命令 /milestone X.Y 将 PR 分配给相关的里程碑。 这会提醒管理此版本的文档人员功能文档即将发布。 如果您的功能不需要任何文档更改,请在 #sig-release Slack 频道中说一下, 以确保 sig-release 团队知道这一点。 如果该功能确实需要文档,但未创建 PR,则该功能可能已从里程碑中删除。
  • 文档截止日期 - PR 审核:您的 PR 现在需要包含功能文档的初稿。不必担心格式或修饰。 只需描述该功能的用途以及使用方法即可。管理发行版的文档人员将与您合作,使内容成形以进行发布。 如果您的功能需要文档且未收到第一稿内容,则该功能可能已从里程碑中删除。
  • 文档完成 - PR 已审核,准备合并:如果您的 PR 尚未在 release-X.Y 此期限之前合并到分支中, 请与管理发行版的文档人员一起合作帮助它合入。 如果您的功能需要文档且文档尚未准备好,该功能可能会从里程碑中删除。

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

贡献其他仓库

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

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

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

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

本地化内容

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

参与本地化工作

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

  • 将 PR 限制为一种语言。

    每种语言都有其自己的审阅者和批准者。

  • 审阅者,请验证 PR 是否仅对一种语言进行了更改。

    如果 PR 包含对一种以上源语言的更改,请 PR 贡献者为每种语言打开单独的 PR。

接下来

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

反馈