From ea32037620fe5c706d157e226add7e413b4fc6e8 Mon Sep 17 00:00:00 2001 From: Hongcai Ren Date: Sun, 29 Sep 2019 20:43:37 +0800 Subject: [PATCH] [zh] Localize contribute/intermediate (#16496) * Copy docs/contribute/intermediate.md first * Finish Review pull requests * Split huge document: This commit finish review a pull request. * Split huge document: Work from a local clone * Split huge document:Triage and categorize issues * Split huge document: Document new features * Split huge document:Localize content * correct title level * Update content/zh/docs/contribute/intermediate.md Co-Authored-By: LiuDui <1693291525@qq.com> --- content/zh/docs/contribute/intermediate.md | 1498 ++++++++++++++++++++ 1 file changed, 1498 insertions(+) create mode 100644 content/zh/docs/contribute/intermediate.md diff --git a/content/zh/docs/contribute/intermediate.md b/content/zh/docs/contribute/intermediate.md new file mode 100644 index 0000000000..82d42e8f4e --- /dev/null +++ b/content/zh/docs/contribute/intermediate.md @@ -0,0 +1,1498 @@ +--- +title: 中级贡献 +slug: intermediate +content_template: templates/concept +weight: 20 +card: + name: contribute + weight: 50 +--- + +{{% capture overview %}} + + +本文假定你已经阅读并掌握了[开始贡献](/docs/contribute/start/)中介绍的内容, +想要了解更多关于贡献的内容。 + + +{{< note >}} +有些任务需要使用Git命令行客户端和其他工具。 +{{< /note >}} + +{{% /capture %}} + +{{% capture body %}} + + +现在,您已经熟悉了Kubernetes文档,并按照[开始贡献](/docs/contribute/start/)文章中介绍的方式进行了贡献, +您可能已经准备好做更多的工作。这些任务假设您已经或愿意获得以下主题领域的更深入的知识: + + +- Kubernetes概念 +- Kubernetes文档工作流 +- 在哪里和如何找到即将推出的Kubernetes功能的信息 +- 较强的研究能力 + + +这些任务不像初学者的任务那样是顺序的。没有人期望一个人会一直做所有的事情。 + +## 评审 pull request + + +通常,每周都会有一个特定的文档审核志愿者对[pull requests 和 issues](#triage-and-categorize-issues) +进行分类和审核。这个人就是本周的“PR 牧马人”。排班计划在[PR 牧马人排班](https://github.com/kubernetes/website/wiki/PR-Wranglers)维护。 +如果想要加入排班计划,需要参加每周的 SIG Docs 会议并志愿申请。 +尽管你不在本周的排班计划中,你也可以审核那些还未开始检视的PR。 + + +除了轮换之外,自动化系统(机器人)会根据修改的文件自动推荐相应的 approver 和 reviewer。 +PR作者应该遵循机器人的指导,这也有助于PR得到快速审查。 + + +我们希望尽快合并和发布pull requests。 +为了确保文档是准确的和最新的,每个PR都需要由理解内容的人以及具有编写优秀文档经验的人来评审。 + + +评审人员和批准人员需要提供可操作的和建设性的反馈,以保持贡献者的参与并帮助他们改进。 +有时候,帮助一个新的贡献者把他们的PR准备好合并比你自己重写它需要更多的时间, +但是从长远来看,当我们有不同的积极参与者时,这个项目会更好。 + + +在开始评审PR之前,请确保熟悉 [文档风格指南](/docs/contribute/style/style-guide/) +和 [行为准则](/community/code-of-conduct/)。 + + +### 找一个PR来评审 + + +要查看所有打开的PR,请转到GitHub仓库中的**Pull Requests**选项卡。 +当符合以下所有条件时,PR才有资格进行评审: + + +- 拥有 `cncf-cla:yes` 标签 +- 描述中没有WIP +- 没有包含`do-not-merge`字样的标签 +- 没有合并冲突 +- 基于正确的分支(通常为“master”,除非PR与某个未发布的功能相关) +- 没有被其他文档人员(或其他技术领域的评审人)评审,除非你被显式的请求参与评审。 + 需要说明的是,如果其他评审已经结束的情况下,你再留下很多新的意见,会让人感到沮丧,这适得其反。 + + +如果PR不符合合并的条件,请留下评论,让作者知道问题所在,并帮助他们解决问题。 +如果他们被告知并在几周或几个月内没有解决问题,最终他们的PR将被关闭而不会合并。 + + +如果您是新手,或者您没有太多的带宽,请寻找具有 `size/XS` 或 `size/S` 标记集的PR。 +大小由PR更改的行数自动设置。 + +#### 评审人员和批准人员 + + +Kubernetes 网站仓库与 Kubernetes 的一些代码仓库在涉及审核者和审批者角色时的操作方式不同。 +有关评审人员和批准人员职责的更多信息,请参见[参与](/docs/contribute/participating/)。 +这里只做一个概述。 + + +- 当评审人员以评审PR的技术准确性时,评审人员发表一个 `/lgtm` 评论表示技术上是无误的。 + + {{< note >}}如果你对技术准确性不确信,不要在涉及文档修改的PR中回复 `/lgtm`。 {{< /note >}} + +- 批准者审核有关文档修改的内容时,注重质量和相关规范(比如[风格规范](/docs/contribute/style/style-guide))。 + 只有在 [`OWNERS`](https://github.com/kubernetes/website/blob/master/OWNERS) 文件中列出的 + 人才可以批准PR。批准PR时,需要回复一个`/approved`评论。 + + +如果PR拥有来自Kubernetes社区的任何人的`/lgtm`评论和来自`sig-docs-maintainers`组的`/approved`评论, +只要它没有被hold并且作者已签署了CLA,PR就会被合并。 + + +### 审核PR + + + + +1. 阅读PR描述,并阅读任何附加的问题或链接,如果有的话。 + “快速评审”有时弊大于利,所以确保你有正确的知识来提供有意义的评审。 + +2. 如果其他人是审核这个PR的最佳人选,请通过添加`/assign @`的评论让他们知道。 + 如果你要求一个非文档人员进行技术评审,但仍然想从文档的角度来评审PR,那就继续吧。 + +3. 转到 **Files changed** 选项卡。查看所有的修改行。删除的内容具有红色背景,这些行也以 `-` 符号开头。 + 添加的内容具有绿色背景,这些行也以 `+` 符号开始。在一行中,实际修改的内容的背景颜色比该行的其余部分略深一些。 + + - 特别是如果PR使用复杂的格式或更改CSS、Javascript或其他站点范围内的元素,您可以使用PR预览网站。 + 转到 **Conversation** 选项卡,单击页面底部附近的 `deploy/netlify` 测试的 **Details** 链接。 + 默认情况下,它会在同一个浏览器窗口中打开,所以在一个新窗口中打开它,这样你就不会丢失你的部分评论。 + 切换回 **Files changed** 选项卡以继续您的审阅。 + - 确保PR符合文档[风格指南](/docs/contribute/style/style-guide/), + 如果不符合,请将作者链接到风格指南的相关部分。 + - 如果您对给定的更改有疑问、评论或其他反馈,请将鼠标悬停在一行上,然后单击出现的蓝白相间的 `+` 号。 + 键入您的评论并单击 **Start a review**。 + + - 如果你有更多的评论,请以同样的方式留下评论。 + - 按照惯例,如果您看到一个与PR的主要目的无关的小问题,比如一个打印错误或空格错误, + 您可以将它指出来,并在注释前加上nit:以便作者知道您认为它是无关紧要的。 + 他们仍然应该解决这个问题。 + - 当您查看完所有内容,或者没有任何评论时,回到页面顶部并单击 **Review changes**。 + 选择**Comment** 或**Request Changes**。添加评审摘要, + 并在评审摘要字段中另起一行添加适当的[Prow 命令](https://prow.k8s.io/command-help)。 + SIG Docs 遵循[Kubernetes代码审查流程](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process)。 + 您所有的意见将在一个单一的评论中发送给PR作者。 + + - 如果您认为PR已经准备好合并,请将文本 `/approve` 添加到摘要中。 + - 如果PR不需要额外的技术审查,也可以同时添加文本 `/lgtm` 。 + - 如果PR *确实* 需要额外的技术审查,使用 `/assign` + GitHub 用户名添加需要提供技术审查的人。 + 查看上面出现的 Markdown 文件中的`reviewers`字段,看看谁可以提供技术审阅。 + - 如果需要阻止PR被合并,加上 `/hold` ,就会设置 `do-not-merge/hold` 标签。 + - 如果PR没有冲突、有 `lgtm` 和 `approved` 标签且没有 `hold` 标签,它就会自动合并。 + - 如果PR拥有 `lgtm` 和 `approved` 后再有新的变更,那么这些标签会自动清除。 + + PR中可能用到的命令,参阅 + [斜线命令列表](https://prow.k8s.io/command-help)。 + + - 如果您以前选择了**Request changes** ,并且PR作者已经处理了您的关注点, + 那么您可以在**Files changed** 选项卡或 **Conversation** 选项卡底部更改您的审阅状态。 + 确保添加 `/approve` 标签,并在必要时指派技术审阅人员,以便合并PR。 + + +### 提交到别人的PR + + +留下评论是有帮助的,但有时你需要把自己的想法融入到其他人的PR中,而不仅仅是留下评论。 + + +除非对方明确要求你“接手”,或者你想重新建立一个长期被抛弃的PR,否则不要急于“接手”。 +虽然短期内这样做可能更快,但会剥夺这个人做出贡献的机会。 + + +您的做法(接手)取决于您是需要编辑已经在PR范围内的文件,还是PR尚未触及的文件。 + + +如果以下任何一件事是符合的,你就不能提交到某人的PR: + + +- 如果PR作者将他们的分支直接推入https://github.com/kubernetes/website/ repository, + 那么只有具有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 + ``` + +3. + 获取远程。这不会更改任何本地文件,但会更新克隆的远程对象的概念(如分支和标记)及其当前状态。 + + ``` + git remote fetch + ``` + +4. + 拉取远程分支。如果已经有同名的本地分支,则此命令将失败。 + + ``` + git checkout + ``` + +5. + 进行更改,使用 `git add` 添加更改,然后提交更改。 + +6. + 将您的更改推到作者的远程。 + + ``` + git push + ``` + +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](https://github.com/kubernetes/website) + 并单击Fork按钮。几秒钟后,您将被重定向到您的fork的URL,它通常类似于`https://github.com//website` , + 除非您已经有一个名为 `website`的存储库。复制这个网址。 + +4. 在你的fork中增加另一个远端 `origin`: + + ``` + git remote add origin + ``` + + +### 使用本地仓库 + + +在本地存储库上启动新的工作单元之前,您需要确定将工作基于哪个分支。 +答案取决于你在做什么,但是下面的指导方针是适用的: + + +- 对于现有内容的一般改进,可以从 `master` 开始。 +- 对于关于Kubernetes发布版本中已经存在的特性的新内容,请从 `master` 开始。 +- 对于多个SIG Docs贡献者将协作的长期工作,例如内容重组,使用为该工作创建的特定功能分支。 +- 对于与即将发布但尚未发布的Kubernetes版本相关的新内容,请使用为该Kubernetes版本创建的预发布特性分支。 + + +更多指导,请参考[选择分支](/docs/contribute/start/#choose-which-git-branch-to-use)。 + + +在您决定要使用哪个分支之后(或者用Git术语来说,基于它), +使用以下工作流来确保您的工作基于该分支的最新版本。 + + +1. + 拉取 `upstream` 和 `origin` 远端。 + 这将更新您对这些分支所包含内容的本地概念,但不会更改您的本地分支。 + + ``` + git fetch upstream + git fetch origin + ``` + +2. + 基于你选择的分支创建一个新的跟踪分支。以你使用master为例: + + ``` + git checkout -b 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中链接问题并将请求拉到一起。 + {{< /note >}} + +5. + 您还可以选择使用hugo命令在本地暂存站点来测试您的更改。[时间看本地更改](#view-your-changes-locally)。 + 您还可以在提交PR后查看更改。 + +6. + 在创建包含本地提交的PR之前,需要将分支推到fork,也就是`origin`端点。 + + ``` + git push origin + ``` + + 从技术上讲,您可以从push命令中省略分支名称,但是这种情况下的行为取决于您使用的Git版本。 + 如果包含分支名称,结果将更加可重复。 + + +7. + 此时,如果您在web浏览器中访问https://github.com/kubernetes/website, GitHub会检测到您将一个新的分支推送到您的fork,并提供创建一个pull请求。填写pull request模板。 + + - 标题不应超过50个字符,并总结更改的意图。 + - + 长表单描述应该包含关于修复的更多信息,如果PR修复了GitHub issue, + 则应该包含类似`Fixes #12345`这样的行。 + 这将导致在合并PR时自动关闭该问题。 + - + 您可以添加标签或其他元数据并分配审阅人员。有关语法,请参见[分类和分类问题](#triage-and-categorize-issues)。 + + 点击 **Create pull request** + +8. + 几个自动化测试将运行与您所应用的更改的网站状态。 + 如果任何测试失败,请单击**Details**链接获取更多信息。 + 如果Netlify测试成功完成,它的**Details**链接将转到Kubernetes网站的阶段性版本, + 其中应用了您的更改。 + 这是审阅人员检查更改的方式。 + +9. + 如果您注意到需要进行更多的更改,或者评审人员给了您反馈,请在本地处理反馈, + 然后再次重复步骤4 - 6,创建一个新的提交。新的提交被添加到您的pull请求中, + 测试再次运行,包括Netlify。 + +10. + 如果审查员将更改添加到您的pull请求中,您需要从fork获取这些更改,然后才能添加更多的更改。 + 假设您的分支当前已签出,请使用以下命令来完成此操作。 + + ``` + git fetch origin + git rebase origin/ + ``` + + 在rebasing之后,您需要添加`-f`标志来强制推送分支。 + + ``` + git push -f origin + ``` + +11. + 如果其他人的更改合并到您工作所基于的分支中,并且您对相同文件的相同部分进行了更改, + 则可能会发生冲突。如果pull请求显示有需要解决的冲突,您可以使用GitHub UI解决它们, + 或者在本地解决它们。 + + 首先执行第10步,确保你的fork仓库与你本地分支一致。 + + + 接着,拉取 `upstream` 并 rebase 你的分支。 + + ``` + git fetch upstream + git rebase upstream/master + ``` + + + 如果存在Git无法自动解决的冲突,可以使用`git status`命令查看冲突文件。 + 对于每个冲突文件,编辑它并查找冲突标记`>>>`,`<<<`,and `===`。 + 解决冲突并删除冲突标记。然后使用`git add `, + 并使用`git rebase --continue`继续将更改添加到更改集中。 + 当所有提交都已应用,并且没有更多冲突时,`git status`将显示您不在rebase中, + 并且不需要提交任何更改。此时,强制将分支推到fork, pull请求应该不再显示任何冲突。 + + +如果您在解决冲突方面遇到困难,或者您被与pull请求相关的任何其他事情卡住, +请在`#sig-docs` Slack通道或[kubernet-sig-docs邮件列表](https://groups.google.com/forum/#!forum/kubernetes-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](https://gohugo.io/getting-started/installing/) 版本 {{< hugoVersion >}} 或更新版本. + +2. + 在终端中,转到您克隆的Kubernetes文档的根目录,并输入以下命令: + + ``` + hugo server + ``` + +3. + 在浏览器地址栏中输入 `localhost:1313`。 + +4. + 如果想停掉本地Hugo实例,只需要在命令行中键入`Ctrl+C`来关闭命令行窗口。 + + +## 问题归类 + + +在任何给定的一周内,一个特定的文档审批者会自愿对pull请求和问题进行初步分类和审查。 +要进入这个名单,参加每周的团体文档会议和志愿者。 +即使你不在这周的时间表上,你仍然可以审核PR。 + + +SIG文档人员只负责对文档问题进行分类和分类。一般的网站问题也归档在`kubernetes/website` 资源库中。 + + +当你对一个问题进行分类时: + + +- 评估这个问题是否有价值。有些问题可以通过回答问题或向作者指出资源来迅速解决。 +- 如果问题没有足够的细节可以采取行动,或者模板没有填好,询问作者更多的信息。 +- 向问题添加标签(有时称为标签)、项目或里程碑。SIG文档团队并没有大量使用项目和里程碑。 +- 根据您的判断,对某个问题拥有所有权并为其提交PR(特别是如果它是快速的或与您已经在做的工作相关的)。 + + +如果你针对问题分类有疑问,请在Slack `#sig-docs` 频道或 +[kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) +中询问。 + + +### 有关标签的更多信息 + + +这些准则并非一成不变,可能会发生变化。 + + +- 一个问题可以有多个标签。 +- 一些标签使用斜杠符号进行分组,可以将其视为“子标签”。例如,`sig/`存在许多标签,例如 `sig/cli` 和 `sig/api-machinery`。 +- 系统会根据问题所涉及文件中的元数据,问题注释中使用的斜杠命令或问题文本中的信息,自动添加一些标签。 +- 由负责问题分类的人员(或报告问题的人员,如果他们是SIG文档批准者)手动添加一些标签。 + - `Actionable`:似乎有足够的信息可以解决或解决此问题。 + - `good first issue`:Kubernetes或SIG Docs经验有限的人也有可能可以解决此问题。 + - `kind/bug`, `kind/feature`, and `kind/documentation`: + 如果提出问题的人未正确填写模板,则可能不会自动分配这些标签。 + 错误是现有内容或功能的问题,功能是对新内容或功能的请求。`kind/documentation`标签当前未使用。 + - 优先级标签:定义问题的相对严重性。 + 这些并没有在[Kubernetes贡献者指导](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority)中, + 可以是一个P1,P2或者P3。 +- 要添加标签,如果您是Sig Docs批准者,则可以使用GitHub的Labels小部件。Kubernetes组织的任何人都可以通过添加评论来添加标签/label 。标签必须已经存在。如果您尝试添加不存在的标签,该命令将被静默忽略。 + + +### 优先级 + + +问题的优先级会影响问题的解决速度。对于文档,以下是设置问题优先级的准则: + +#### P1 + + +- 影响超过1页的主要内容错误 +- 大量访问的页面上的代码示例损坏 +- “入门”页面上的错误 +- 众所周知或广为宣传的客户痛点 +- 自动化问题 + +#### P2 + + + + +- 不经常使用的示例代码损坏 +- 页面流量过大的次要内容问题 +- 流量较低的页面上的主要内容问题 + + +#### P3 + + +- 错别字和损坏的链接 +- 文档功能要求 +- “有了更好(没有也问题不大)”项目 + + +### 处理特殊问题类型 + + +我们经常遇到以下类型的问题,有必要记录如何处理它们。 + + +#### 重复的问题 + + +如果单个问题可以解决一个或多个问题,则应将该问题合并为一个问题。 +您应该决定哪个问题保持打开状态(或打开一个新问题),移植所有相关信息,链接相关问题, +并关闭描述同一问题的所有其他问题。只处理一个问题将有助于减少混乱并避免重复处理同一问题。 + + +#### 无效链接问题 + + +根据报告无效链接的位置,需要采取不同的措施来解决此问题。 +API和Kubectl文档中的无效链接是自动化问题,应分配为P1,直到可以完全解决该问题为止。 +所有其他无效链接都是需要手动修复的问题,可以将其分配为P3。 + + +#### 博客问题 + + +随着时间的流逝,Kubernetes博客条目预计会过时, +因此我们仅保留不到一年的博客条目。 +如果某个问题与存在超过一年的博客条目有关,则应将其关闭而不进行修复。 + + +#### 支持请求或代码错误报告 + + +相反,为文档带来的一些问题是底层代码的问题, +或者在某些内容(例如教程)不起作用时请求帮助。 +对于与文档无关的问题,请关闭issue并指示请求者正确的支持场所(Slack,Stack Overflow), +并在适当的地方针对具有功能缺陷的问题提出问题(可以从kubernetes/kubernetes开始)。 + + +对支持请求的响应示例: + +```none +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. +``` + + +示例代码错误报告响应: + +```none +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会议 +(请参阅[社区](https://kubernetes.io/community/)页面以获取即将举行的会议, +并在[kubernetes/sig-release](https://github.com/kubernetes/sig-release/) 存储库中监视特定于发行版的文档。 +每个发行版在[/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases) + 目录下都有一个子目录。每个子目录包含一个发布计划,一个发布说明草稿以及一个列出发布团队中每个人的文档。 + + +- 发布时间表包含与发布有关的所有其他文档,会议,会议记录和里程碑的链接。 + 它还包含有关该发行版的目标和时间表的信息,以及此发行版的任何特殊流程。 + 在文档底部附近,定义了几个与发布相关的术语。 + + 本文档还包含**Feature tracking sheet**的链接,这是查找排定要发布的所有新功能的正式方法。 + +- 发布团队文档列出了负责每个发布角色的人员。 + 如果不清楚要与谁谈论某个特定功能或问题,请参加发布会议询问您的问题, + 或者与发布负责人联系,以便他们可以重定向您。 +- 发行说明草稿是了解更多有关特定功能,更改,不推荐使用以及更多有关发行版本的好地方。 + 该内容要到发布周期的后期才能最终确定,因此请谨慎使用。 + + +#### 功能跟踪表 + + +给定Kubernetes版本的功能跟踪表 列出了计划发布的每个功能。 +每个订单项都包含功能名称,功能主要GitHub问题的链接,其稳定性级别(Alpha,Beta或Stable), +SIG和负责实施此功能的人员,是否需要文档,发布说明草稿功能,以及是否已合并。请记住以下几点: + + +- Beta和稳定功能通常比Alpha功能具有更高的文档优先级。 +- 很难测试(因此要文档记录)尚未合并的功能,或者至少在其PR中被认为功能完整的功能。 +- 确定某个功能是否需要文档是一个手动过程,并且仅仅因为某个功能未标记为需要文档并不意味着它就不需要它们。 + + +### 记录功能 + + +如上所述,新功能的草案内容通常由负责实施新功能的SIG提交。 +这意味着您的角色可能更像是给定功能的牧羊人角色。 + + +选择要记录/跟踪的功能后,请在 `#sig-docs` Slack频道, +每周一次的sig-docs会议中或直接在功能SIG提交的PR上询问有关功能。 +如果得到批准,则可以使用[提交到别人的PR](#commit-into-another-persons-pr) +中介绍的技术来编辑 PR。 + + +如果您需要编写新主题,则以下链接很有用: + + +- [撰写新主题](/docs/contribute/style/write-new-topic/) +- [使用页面模板](/docs/contribute/style/page-templates/) +- [文档样式指南](/docs/contribute/style/style-guide/) + + +SIG成员记录了新功能 + + +如果您是Kubernetes开发新功能的SIG成员,则需要一并更新SIG文档, +以确保在发布该功能时及时记录了您的功能。 +查看 [功能跟踪电子表格](https://github.com/kubernetes/sig-release/tree/master/releases), + 或在 #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功能并且由[功能开关](/docs/reference/command-line-tools-reference/feature-gates/) +控制,请确保将其作为PR的一部分添加到功能开关。 +如果您的功能要移出Alpha,请确保将其从该文件中删除。 + + +## 贡献其他仓库 + + +该Kubernetes项目包含超过50个仓库。 +这些存储库中许多都包含可以视为文档的代码或内容,例如面向用户的帮助文本,错误消息, +API参考中的面向用户的文本,甚至是代码注释。 + + +如果您看到文本并且不确定其来源,则可以在Kubernetes组织级别使用GitHub的搜索工具在所有存储库中搜索该文本。 +这可以帮助您确定将问题或PR提交到哪里。 + + +每个存储库可能都有自己的流程和过程。 +在您提交的问题或提交PR,查看存储库的`README.md`,`CONTRIBUTING.md`以及 `code-of-conduct.md`。 + + +大多数存储库使用issue和PR模板。 +浏览一些未解决的问题和PR,以了解该团队的流程。 +提交问题或PR时,​​请确保尽可能详细地填写模板。 + + +## 本地化内容 + + +Kubernetes文档首先是用英语编写的,但是我们希望人们能够使用他们选择的语言来阅读它。 +如果您愿意用另一种语言编写,尤其是在软件领域,则可以帮助本地化Kubernetes文档 +或提供有关现有本地化内容的反馈。 +请参阅[本地化](/docs/contribute/localization/) , +并在[kubernetes-sig-docs邮件列表][kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) #sig-docs上询问,或者在Slack上询问是否有帮助的兴趣。 + + +### 参与本地化工作 + + +请遵循以下准则来使用本地化内容: + + +- 将PR限制为一种语言。 + + 每种语言都有其自己的审阅者和批准者。 + +- 审阅者,请验证PR是否仅对一种语言进行了更改。 + + 如果PR包含对一种以上源语言的更改,请PR贡献者为每种语言打开单独的PR。 + +{{% /capture %}} + +{{% capture whatsnext %}} + + +如果您熟悉本主题中讨论的所有任务,并且想与Kubernetes文档小组进行更深入的接触, +请阅读[高级文档贡献者](/docs/contribute/advanced/)主题。 +{{% /capture %}}