本节包含你在贡献新内容之前需要知晓的信息。
插图 - 贡献新内容准备工作
上图描述了你在提交新内容之前需要知晓的信息。 详细信息见下文。
/content/zh-cn/docs/ 目录下找到 Kubernetes 文档。
某些参考文档是使用位于 update-imported-docs/ 目录下的脚本自动生成的。/content/ 目录下。
每种语言都有一个自己的目录，用两个字母表示，这两个字母是基于
ISO 639-1 标准来确定的。
例如，英语文档的源代码位于 /content/en/docs/ 目录下。所有 Kubernetes 贡献者必须阅读贡献者指南 并签署贡献者授权同意书 (Contributor License Agreement, CLA)。
若贡献者尚未签署 CLA，其发起的 PR 将无法通过自动化测试。
你所提供的姓名和邮件地址必须与 git config 中配置的完全相同，
而且你的 Git 用户名和邮件地址必须与用来签署 CNCF CLA 的信息一致。
在发起 PR 时，你需要预先知道基于哪个分支来开展工作。
| 场景 | 分支 |
|---|---|
| 针对当前发行版本的，对现有英文内容的修改或新的英文内容 | main |
| 针对功能特性变更的内容 | 分支对应于功能特性变更的主要和次要版本，分支名称采用 dev-<version> 的模式。例如，如果某功能特性在 v1.36 版本发生变化，则对应的文档变化要添加到 dev-1.36 分支。 |
| 其他语言的内容（本地化） | 基于本地化团队的约定。参见本地化分支策略了解更多信息。 |
如果你仍不能确定要选择哪个分支，请在 Slack 的 #sig-docs 频道上提出问题。
如果你已经提交了 PR，并且发现所针对的分支选错了，你（且只有作为提交人的你）可以更改分支。
请确保每个 PR 仅涉及一种语言。 如果你需要对多种语言下的同一代码示例进行相同的修改，也请为每种语言发起一个独立的 PR。
kubernetes/website 仓库的文档贡献者工具目录中包含了一些工具，
有助于使你的贡献过程更为顺畅。
代码开发者们：如果你在为下一个 Kubernetes 发行版本中的某功能特性撰写文档， 请参考为发行版本撰写功能特性文档。
要贡献新的内容页面或者改进已有内容页面，请发起拉取请求（PR）。 请确保你满足了开始之前一节中所列举的所有要求。
如果你所提交的变更足够小，或者你对 git 工具不熟悉， 可以阅读使用 GitHub 提交变更以了解如何编辑页面。
如果所提交的变更较大， 请阅读基于本地克隆副本开展工作以学习如何在你本地计算机上进行修改。
如果你在 git 工作流方面欠缺经验，这里有一种发起拉取请求的更为简单的方法。 图 1 勾勒了后续的步骤和细节。
图 1. 使用 GitHub 发起一个 PR 的步骤。
在你发现问题的页面上，选择右侧导航面板中的编辑此页面选项。
在 GitHub 的 Markdown 编辑器中修改内容。
在编辑器右上方，选择 Commit changes。。 在第一个字段中，为你的提交消息取一个标题。 在第二个字段中，为你的提交写一些描述文字。
不要在提交消息中使用 GitHub 关键词。 你可以在后续的 PR 描述中使用这些关键词。
选择 Propose changes。
选择 Create pull request。
出现 Open a pull request 界面。填写表单：
PR 描述信息是帮助 PR 评阅人了解你所提议的变更的重要途径。 更多信息请参考发起一个 PR。
在合并 PR 之前，Kubernetes 社区成员会评阅并批准它。
k8s-ci-robot 会基于页面中最近提及的属主来建议评阅人（reviewers）。
如果你希望特定某人来评阅，可以留下评论，提及该用户的 GitHub 用户名。
如果某个评阅人请你修改 PR：
如果你希望等待评阅人的反馈，可以每 7 天左右联系一次。
你也可以在 #sig-docs Slack 频道发送消息。
当评阅过程结束，某个评阅人会合并你的 PR。 几分钟之后，你所做的变更就会上线了。
如果你有 Git 的使用经验，或者你要提议的修改不仅仅几行，请使用本地克隆副本来开展工作。
首先要确保你在本地计算机上安装了 Git。 你也可以使用 Git 的带用户界面的应用。
图 2 显示了基于本地克隆副本开展工作的步骤。每个步骤的细节如下。
图 2. 使用本地克隆副本进行修改。
kubernetes/website 仓库；打开终端窗口，克隆你所派生的副本，并更新 Docsy Hugo 主题：
git clone git@github.com:<github_username>/website
cd website
前往新的 website 目录，将 kubernetes/website 仓库设置为 upstream
远端：
cd website
git remote add upstream https://github.com/kubernetes/website.git
确认你现在有两个仓库 origin 和 upstream：
git remote -v
输出类似于：
origin git@github.com:<github_username>/website.git (fetch)
origin git@github.com:<github_username>/website.git (push)
upstream https://github.com/kubernetes/website.git (fetch)
upstream https://github.com/kubernetes/website.git (push)
从你的克隆副本取回 origin/main 分支，从 kubernetes/website
取回 upstream/main：
git fetch origin
git fetch upstream
这样可以确保你本地的仓库在开始工作前是最新的。
此工作流程与 Kubernetes 社区 GitHub 工作流有所不同。
在推送你的变更到你的远程派生副本库之前，你不需要将你本地的 main 与 upstream/main 合并。
决定你要基于哪个分支来开展工作：
upstream/main。upstream/main。如果你在选择分支上需要帮助，请在 #sig-docs Slack 频道提问。
基于第 1 步中选定的分支，创建新分支。
下面的例子假定基础分支是 upstream/main：
git checkout -b <my_new_branch> upstream/main
在任何时候，都可以使用 git status 命令查看你所改变了的文件列表。
当你准备好发起拉取请求（PR）时，提交你所做的变更。
在你的本地仓库中，检查你要提交的文件：
git status
输出类似于：
On branch <my_new_branch>
Your branch is up to date with 'origin/<my_new_branch>'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: content/en/docs/contribute/new-content/contributing-content.md
no changes added to commit (use "git add" and/or "git commit -a")
将 Changes not staged for commit 下列举的文件添加到提交中：
git add <your_file_name>
针对每个文件重复此操作。
添加完所有文件之后，创建一个提交（commit）：
git commit -m "Your commit message"
推送你本地分支及其中的新提交到你的远程派生副本库：
git push origin <my_new_branch>
在推送变更或者发起 PR 之前在本地查看一下预览是个不错的主意。 本地预览这篇文章解释了如何在本地运行网站并预览建议的更改。
另一种方式是，在你的本地计算机上安装并使用 hugo 命令：
安装 website/netlify.toml
文件中指定的 Hugo（扩展版）
和 Node 版本。
安装所有依赖项：
npm ci
启动一个终端窗口，进入 Kubernetes 网站仓库目录，启动 Hugo 服务器：
cd <path_to_your_repo>/website
make server
如果你使用的是 Windows 机器或无法运行 make 命令，请使用以下命令：
hugo server --buildFuture
在浏览器的地址栏输入： http://localhost:1313。
Hugo 会监测文件的变更并根据需要重新构建网站。
要停止本地 Hugo 实例，返回到终端窗口并输入 Ctrl+C 或者关闭终端窗口。
图 3 显示了从你的克隆副本向 kubernetes/website 发起 PR 的步骤。 详细信息如下。
请注意，贡献者可以将 kubernetes/website 称为 k/website。
图 3. 从你的克隆副本向 kubernetes/website 发起一个 PR 的步骤。
在 Web 浏览器中，前往 kubernetes/website 仓库；
点击 New Pull Request；
选择 compare across forks；
从 head repository 下拉菜单中，选取你的派生仓库；
从 compare 下拉菜单中，选择你的分支；
点击 Create Pull Request；
为你的拉取请求添加一个描述：
Title （不超过 50 个字符）：总结变更的目的；
Description：给出变更的详细信息；
Fixes #12345 或
Closes #12345。GitHub 的自动化设施能够在当前 PR 被合并时自动关闭所提及
的 Issue。如果有其他相关联的 PR，也可以添加对它们的链接。点击 Create pull request 按钮。
祝贺你！你的拉取请求现在出现在 Pull Requests 列表中了！
在发起 PR 之后，GitHub 会执行一些自动化的测试，并尝试使用 Netlify 部署一个预览版本。
GitHub 也会自动为 PR 分派一些标签，以帮助评阅人。 如果有需要，你也可以向 PR 添加标签。 欲了解相关详细信息，可以参考 添加和删除 Issue 标签。
在本地完成修改之后，可以修补（amend）你之前的提交：
git commit -a --amend
-a：提交所有修改--amend：对前一次提交进行增补，而不是创建新的提交如果有必要，更新你的提交消息；
使用 git push origin <my_new_branch> 来推送你的变更，重新触发 Netlify 测试。
有时评阅人会向你的 PR 中提交修改。在作出其他修改之前，请先取回这些提交。
从你的远程派生副本仓库取回提交，让你的工作分支基于所取回的分支：
git fetch origin
git rebase origin/<your-branch-name>
变更基线（rebase）操作完成之后，强制推送本地的新改动到你的派生仓库：
git push --force-with-lease origin <your-branch-name>
#sig-docs Slack 频道寻求帮助。如果另一个贡献者在别的 PR 中提交了对同一文件的修改，这可能会造成合并冲突。 你必须在你的 PR 中解决所有合并冲突。
更新你的派生副本，重设本地分支的基线：
git fetch origin
git rebase origin/<your-branch-name>
之后强制推送修改到你的派生副本仓库：
git push --force-with-lease origin <your-branch-name>
从 kubernetes/website 的 upstream/main 分支取回更改，然后重设本地分支的基线：
git fetch upstream
git rebase upstream/main
检查重设基线操作之后的状态：
git status
你会看到一组存在冲突的文件。
打开每个存在冲突的文件，查找冲突标记：>>>、<<< 和 ===。
解决完冲突之后删除冲突标记。
进一步的详细信息可参见 冲突是怎样表示的.
添加文件到变更集合：
git add <filename>
继续执行基线变更（rebase）操作：
git rebase --continue
根据需要重复步骤 2 到 5。
在应用完所有提交之后，git status 命令会显示 rebase 操作完成。
将分支强制推送到你的派生仓库：
git push --force-with-lease origin <your-branch-name>
PR 不再显示存在冲突。
要了解更多信息，可参看
Git Tools - Rewriting History，
或者在 #sig-docs Slack 频道寻求帮助。
如果你的 PR 包含多个提交（commits），你必须将其压缩成一个提交才能被合并。
你可以在 PR 的 Commits Tab 页面查看提交个数，也可以在本地通过
git log 命令查看提交个数。
本主题假定使用 vim 作为命令行文本编辑器。
启动一个交互式的 rebase 操作：
git rebase -i HEAD~<number_of_commits_in_branch>
压缩提交的过程也是一种重设基线的过程。
这里的 -i 开关告诉 git 你希望交互式地执行重设基线操作。
HEAD~<number_of_commits_in_branch 表明在 rebase 操作中查看多少个提交。
输出类似于；
pick d875112ca Original commit
pick 4fa167b80 Address feedback 1
pick 7d54e15ee Address feedback 2
# Rebase 3d18sf680..7d54e15ee onto 3d183f680 (3 commands)
...
# These lines can be re-ordered; they are executed from top to bottom.
输出的第一部分列举了重设基线操作中的提交。
第二部分给出每个提交的选项。
改变单词 pick 就可以改变重设基线操作之后提交的状态。
就重设基线操作本身，我们关注 squash 和 pick 选项。
进一步的详细信息可参考 Interactive Mode。
开始编辑文件。
修改原来的文本：
pick d875112ca Original commit
pick 4fa167b80 Address feedback 1
pick 7d54e15ee Address feedback 2
使之成为：
pick d875112ca Original commit
squash 4fa167b80 Address feedback 1
squash 7d54e15ee Address feedback 2
以上编辑操作会压缩提交 4fa167b80 Address feedback 1 和 7d54e15ee Address feedback 2
到 d875112ca Original commit 中，只留下 d875112ca Original commit 成为时间线中的一部分。
保存文件并退出编辑器。
推送压缩后的提交：
git push --force-with-lease origin <branch_name>
Kubernetes 项目包含大约 50 多个仓库。 这些仓库中很多都有文档：提供给最终用户的帮助文本、错误信息、API 参考或者代码注释等。
如果你发现有些文本需要改进，可以使用 GitHub 来搜索 Kubernetes 组织下的所有仓库。 这样有助于发现要在哪里提交 Issue 或 PR。
每个仓库有其自己的流程和过程。在登记 Issue 或者发起 PR 之前，
记得阅读仓库可能存在的 README.md、CONTRIBUTING.md 和
code-of-conduct.md 文件。
大多数仓库都有自己的 Issue 和 PR 模板。 通过查看一些待解决的 Issue 和 PR， 你可以大致了解协作的流程。 在登记 Issue 或提出 PR 时，务必尽量填充所给的模板，多提供详细信息。
Kubernetes 的每个主要版本发布都会包含一些需要文档说明的新功能。 新的发行版本也会更新已有的功能特性和文档（例如将某功能特性从 Alpha 升级为 Beta）。
通常，负责某功能特性的 SIG 要为功能特性的文档草拟文档，并针对 kubernetes/website
仓库的合适的开发分支发起拉取请求。
SIG Docs 团队会提供文字方面的反馈意见，或者直接编辑文档草稿。
本节讨论两个小组在分支方面和发行期间所遵从的流程方面的约定。
要了解有关博客上发布新特性的信息， 请阅读发布沟通。
一般而言，文档贡献者不会为某个发行版本从头撰写文档。 相反，他们会与开发该功能特性的 SIG 团队一起，对文档草稿进行润色， 使之符合发布条件。
在你选定了某个功能特性，为其撰写文档（主笔或辅助），请在 #sig-docs Slack 频道、SIG Docs 的每周例会上，
或者在功能特性对应的 PR 上提出咨询。如果继续工作是没有问题的，
你可以使用提交到他人的 PR
所述的某个技巧参与 PR 的编辑工作。
要了解即将发布的功能特性，可以参加每周的 SIG Release 例会 （参考社区页面，了解即将召开的会议）， 监视 kubernetes/sig-release 中与发行相关的文档。 每个发行版本在 /sig-release/tree/master/releases/ 下都有一个对应的子目录。 该子目录包含了发行版本的时间计划、发行公告的草稿以及列举发行团队名单的文档。
发行时间计划文件中包含到所有其他文档、会议、会议记录及发行相关的里程碑的链接。 其中也包含关于发行版本的目标列表、时间线，以及当前发行版本中就绪的特殊流程的信息。 文档末尾附近定义了若干与该发行版本有关的术语。
此文档也包含到功能特性跟踪清单的链接。 这一清单是了解哪些功能特性计划进入某发行版本的正式途径。
发行团队文档列举了哪些人扮演着各个发行版本的不同角色。 如果不清楚要联系谁来讨论特定的功能特性或者回答你的问题， 你可以参加发行团队的会议，提出你的问题，或者联系发行团队的牵头人， 这样他们就可以帮你找到正确的联系人。
发行说明草稿是用来发现与特定发行版本相关的功能特性、变更、废弃以及其他信息的好来源。 由于在发行周期的后段该文档的内容才会最终定稿，参考其中的信息时请谨慎。
针对给定 Kubernetes 发行版本 特性跟踪清单中列举的是计划包含于该版本中的每个功能特性。 每一行中都包含特性的名称、特性对应的主要 GitHub Issue，其稳定性级别（Alpha、 Beta 或 Stable）、负责实现该特性的 SIG 和个人、是否该特性需要文档、 该特性的发行说明草稿以及该特性是否已经被合并等等。阅读此清单时请注意：
本节中的信息是针对为发行版本中新功能特性撰写文档的来自其他 Kubernetes SIG 的成员。
如果你是某个 SIG 的成员，负责为 Kubernetes 开发某一项新的功能特性，你需要与
SIG Docs 一起工作，确保这一新功能在发行之前已经为之撰写文档。
请参考特性跟踪清单或者
Kubernetes Slack 上的 #sig-release 频道，检查时间安排的细节以及截止日期。
kubernetes/website 仓库上针对 dev-1.36
分支提交一个draft PR，其中包含较少的、待以后慢慢补齐的提交内容。
要创建一个草案（draft）状态的 PR，可以在 Create Pull Request 下拉菜单中选择
Create Draft Pull Request，然后点击 Draft Pull Request。如果对应的功能特性不需要任何类型的文档变更，请通过在 #sig-release Slack
频道声明这一点以确保 sig-release 团队了解。
如果功能特性确实需要文档，而没有对应的 PR
提交，该功能特性可能会被从里程碑中移除。
时机成熟时，你可以在你的占位 PR 中完成功能特性文档，并将 PR 的状态从草案状态更改为 Ready for Review。要将一个拉取请求标记为已准备好评阅， 转到页面的 merge 框，点击 Ready for review。
尽可能为功能特性提供详尽文档以及使用说明。如果你需要文档组织方面的帮助，
请在 #sig-docs Slack 频道中提问。
当你已经完成内容撰写，指派给你的功能特性的文档贡献者会去评阅文档。 为了确保技术准确性，内容可能还需要相应 SIG 的技术审核。 尽量利用他们所给出的建议，改进文档内容以达到发布就绪状态。
如果你的特性需要文档，而你未提交初版文档，那此特性可能会被从里程碑中移除。
如果你在处理的特性处于 Alpha 或 Beta 阶段并由某特性门控控制，
你需要在 content/en/docs/reference/command-line-tools-reference/feature-gates/ 目录中为其创建一个特性门控文件。
文件名应为特性门控的名称，并以 .md 作为后缀。
你可以参照同一目录中已存在的其他文件，以了解你的文件应该是什么样子的。
通常一段话就够了；若要长篇阐述，请在其他地方添加文档，并为其添加链接。
此外，为了确保你的特性门控出现在 Alpha/Beta 特性门控表格中， 请在 Markdown 描述文件的 Front Matter 中包含以下细节：
stages:
- stage: <alpha/beta/stable/deprecated> # 指定特性门控的开发阶段
defaultValue: <true or false> # 如果默认启用，则设置为 true，否则为 false
fromVersion: <Version> # 特性门控可用的起始版本
toVersion: <Version> # （可选）特性门控可用的结束版本
对于全新的特性门控，还需要一个单独的特性门控描述；在
content/en/docs/reference/command-line-tools-reference/feature-gates/
目录中创建一个新的 Markdown 文件（把其他文件用作模板）。
当你将特性门控从默认禁用更改为默认启用时，你可能还需要更改其他文档（不仅仅是特性门控列表）。
参照这样的话术 “exampleSetting 字段是一个 Beta 字段，默认禁用。
你可以通过启用 ProcessExampleThings 特性门控来启用此字段。”
如果你的特性已经是 GA（正式发布）或已弃用的，请在描述文件的 stages 块中包含一个额外的 stage 条目。
确保 Alpha 和 Beta 阶段保持不变。这一步将特性门控从
Alpha/Beta 特性门控
表格移到已毕业或已弃用的特性门控表格。
例如：
stages:
- stage: alpha
defaultValue: false
fromVersion: "1.12"
toVersion: "1.12"
- stage: beta
defaultValue: true
fromVersion: "1.13"
# 将 `toVersion` 添加到了前一个 stage
toVersion: "1.18"
# 将 'stable' stage 代码块添加到了 stages 下
- stage: stable
defaultValue: true
fromVersion: "1.19"
toVersion: "1.27"最终，Kubernetes 将完全停止包含此特性门控。为了表示某特性门控已被移除，
请在相应描述文件的 Front Matter 中包括 removed: true。
这种变更意味着特性门控及其描述从已毕业或已弃用的特性门控
部分移到名为特性门控（已移除）的专用页面。
如果你的 PR 在发行截止日期之前尚未合并到 dev-1.36 分支，
请与负责管理该发行版本的文档团队成员一起合作，在截止期限之前将其合并。
如果功能特性需要文档，而文档并未就绪，该特性可能会被从里程碑中去除。
案例分析用来概述组织如何使用 Kubernetes 解决现实世界的问题。 Kubernetes 市场化团队和 CNCF 成员会与你一起工作， 撰写所有的案例分析。
案例分析需要经过广泛的评审后，才能被批准合并。
请查看现有案例分析的源码。
参考案例分析指南， 根据指南中的注意事项提交你的 PR 请求。