贡献新内容

• 1: 发起拉取请求（PR）
• 2: 为发行版本撰写功能特性文档
• 3: 提交博客和案例分析

1 - 发起拉取请求（PR）

要贡献新的内容页面或者改进已有内容页面，请发起拉取请求（PR）。 请确保你满足了开始之前一节中所列举的所有要求。

如果你所提交的变更足够小，或者你对 git 工具不熟悉， 可以阅读使用 GitHub 提交变更以了解如何编辑页面。

如果所提交的变更较大， 请阅读基于本地克隆副本开展工作以学习如何在你本地计算机上进行修改。

使用 GitHub 提交变更

如果你在 git 工作流方面欠缺经验，这里有一种发起拉取请求的更为简单的方法。 图 1 勾勒了后续的步骤和细节。

图 1. 使用 GitHub 发起一个 PR 的步骤。

1. 在你发现问题的页面上，选择右侧导航面板中的编辑此页面选项。

2. 在 GitHub 的 Markdown 编辑器中修改内容。

3. 在编辑器的下方，填写 Propose file change 表单。 在第一个字段中，为你的提交消息取一个标题。 在第二个字段中，为你的提交写一些描述文字。

   说明：

   不要在提交消息中使用 GitHub 关键词。 你可以在后续的 PR 描述中使用这些关键词。

4. 选择 Propose File Change。

5. 选择 Create pull request。

6. 出现 Open a pull request 界面。填写表单：

   • Subject 字段默认为提交的概要信息，你可以根据需要进行修改。
   • Body 字段包含更为详细的提交消息（如果你之前有填写过的话）和一些模板文字。 填写模板所要求的详细信息，之后删除多余的模板文字。
   • 确保 Allow edits from maintainers 复选框被勾选。

   说明：

   PR 描述信息是帮助 PR 评阅人了解你所提议的变更的重要途径。 更多信息请参考发起一个 PR。

7. 选择 Create pull request。

在 GitHub 上处理反馈意见

在合并 PR 之前，Kubernetes 社区成员会评阅并批准它。 k8s-ci-robot 会基于页面中最近提及的属主来建议评阅人（reviewers）。 如果你希望特定某人来评阅，可以留下评论，提及该用户的 GitHub 用户名。

如果某个评阅人请你修改 PR：

1. 前往 Files changed Tab 页面；
2. 选择 PR 所修改的任何文件所对应的铅笔（edit）图标；
3. 根据建议作出修改；
4. 提交所作修改。

如果你希望等待评阅人的反馈，可以每 7 天左右联系一次。 你也可以在 #sig-docs Slack 频道发送消息。

当评阅过程结束，某个评阅人会合并你的 PR。 几分钟之后，你所做的变更就会上线了。

基于本地克隆副本开展工作

如果你有 git 的使用经验，或者你要提议的修改不仅仅几行，请使用本地克隆副本来开展工作。

首先要确保你在本地计算机上安装了 git。 你也可以使用 git 的带用户界面的应用。

图 2 显示了基于本地克隆副本开展工作的步骤。每个步骤的细节如下。

图 2. 使用本地克隆副本进行修改。

派生 kubernetes/website 仓库

1. 前往 kubernetes/website 仓库；
2. 选择 Fork.

创建一个本地克隆副本并指定 upstream 仓库

1. 打开终端窗口，克隆你所派生的副本，并更新 Docsy Hugo 主题：

   git clone git@github.com:<github_username>/website
   cd website
   git submodule update --init --recursive --depth 1
   

2. 前往新的 website 目录，将 kubernetes/website 仓库设置为 upstream 远端：

   cd website
   
   git remote add upstream https://github.com/kubernetes/website.git
   

3. 确认你现在有两个仓库 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)
   

4. 从你的克隆副本取回 origin/main 分支，从 kubernetes/website 取回 upstream/main：

   git fetch origin
   git fetch upstream
   

   这样可以确保你本地的仓库在开始工作前是最新的。

   说明：

   此工作流程与 Kubernetes 社区 GitHub 工作流有所不同。 在推送你的变更到你的远程派生副本库之前，你不需要将你本地的 main 与 upstream/main 合并。

创建一个分支

1. 决定你要基于哪个分支来开展工作：

   • 针对已有内容的改进，请使用 upstream/main。
   • 针对已有功能特性的新文档内容，请使用 upstream/main。
   • 对于本地化内容，请基于本地化的约定。 可参考本地化 Kubernetes 文档了解详细信息。
   • 对于在下一个 Kubernetes 版本中新功能特性的文档，使用独立的功能特性分支。 参考为发行版本撰写功能特性文档了解更多信息。
   • 对于很多 SIG Docs 共同参与的，需较长时间才完成的任务，例如内容的重构， 请使用为该任务创建的特性分支。

   如果你在选择分支上需要帮助，请在 #sig-docs Slack 频道提问。

2. 基于第 1 步中选定的分支，创建新分支。 下面的例子假定基础分支是 upstream/main：

   git checkout -b <my_new_branch> upstream/main
   

3. 使用文本编辑器进行修改。

在任何时候，都可以使用 git status 命令查看你所改变了的文件列表。

提交你的变更

当你准备好发起拉取请求（PR）时，提交你所做的变更。

1. 在你的本地仓库中，检查你要提交的文件：

   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")
   

2. 将 Changes not staged for commit 下列举的文件添加到提交中：

   git add <your_file_name>
   

   针对每个文件重复此操作。

3. 添加完所有文件之后，创建一个提交（commit）：

   git commit -m "Your commit message"
   

   说明：

   不要在提交消息中使用任何 GitHub 关键词。 你可以在后续的 PR 描述中使用这些关键词。

4. 推送你本地分支及其中的新提交到你的远程派生副本库：

   git push origin <my_new_branch>
   

在本地预览你的变更

在推送变更或者发起 PR 之前在本地查看一下预览是个不错的主意。 通过预览你可以发现构建错误或者 Markdown 格式问题。

你可以构建网站的容器镜像或者在本地运行 Hugo。 构建容器镜像的方式比较慢，不过能够显示 Hugo 短代码（shortcodes）， 因此对于调试是很有用的。

• 在容器内执行 Hugo
• 在命令行执行 Hugo

git submodule update --init --recursive --depth 1

从你的克隆副本向 kubernetes/website 发起拉取请求（PR）

图 3 显示了从你的克隆副本向 kubernetes/website 发起 PR 的步骤。 详细信息如下。

请注意，贡献者可以将 kubernetes/website 称为 k/website。

图 3. 从你的克隆副本向 kubernetes/website 发起一个 PR 的步骤。

1. 在 Web 浏览器中，前往 kubernetes/website 仓库；

2. 点击 New Pull Request；

3. 选择 compare across forks；

4. 从 head repository 下拉菜单中，选取你的派生仓库；

5. 从 compare 下拉菜单中，选择你的分支；

6. 点击 Create Pull Request；

7. 为你的拉取请求添加一个描述：

   • Title （不超过 50 个字符）：总结变更的目的；

   • Description：给出变更的详细信息；

     • 如果存在一个相关联的 GitHub Issue，可以在描述中包含 Fixes #12345 或 Closes #12345。GitHub 的自动化设施能够在当前 PR 被合并时自动关闭所提及 的 Issue。如果有其他相关联的 PR，也可以添加对它们的链接。
     • 如果你特别希望获得某方面的建议，可以在描述中包含你希望评阅人思考的问题。

8. 点击 Create pull request 按钮。

祝贺你！你的拉取请求现在出现在 Pull Requests 列表中了！

在发起 PR 之后，GitHub 会执行一些自动化的测试，并尝试使用 Netlify 部署一个预览版本。

• 如果 Netlify 构建操作失败，可选择 Details 了解详细信息。
• 如果 Netlify 构建操作成功，选择 Details 会打开 Kubernetes 的一个预览版本， 其中包含了你所作的变更。评阅人也使用这一功能来检查你的变更。

GitHub 也会自动为 PR 分派一些标签，以帮助评阅人。 如果有需要，你也可以向 PR 添加标签。 欲了解相关详细信息，可以参考 添加和删除 Issue 标签。

在本地处理反馈

1. 在本地完成修改之后，可以修补（amend）你之前的提交：

   git commit -a --amend
   

   • -a：提交所有修改
   • --amend：对前一次提交进行增补，而不是创建新的提交

2. 如果有必要，更新你的提交消息；

3. 使用 git push origin <my_new_branch> 来推送你的变更，重新触发 Netlify 测试。

   说明：

   如果你使用 git commit -m 而不是增补参数，在 PR 最终合并之前你必须 squash 你的提交。

来自评阅人的修改

有时评阅人会向你的 PR 中提交修改。在作出其他修改之前，请先取回这些提交。

1. 从你的远程派生副本仓库取回提交，让你的工作分支基于所取回的分支：

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

2. 变更基线（rebase）操作完成之后，强制推送本地的新改动到你的派生仓库：

   git push --force-with-lease origin <your-branch-name>
   

合并冲突和重设基线

如果另一个贡献者在别的 PR 中提交了对同一文件的修改，这可能会造成合并冲突。 你必须在你的 PR 中解决所有合并冲突。

1. 更新你的派生副本，重设本地分支的基线：

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

   之后强制推送修改到你的派生副本仓库：

   git push --force-with-lease origin <your-branch-name>
   

2. 从 kubernetes/website 的 upstream/main 分支取回更改，然后重设本地分支的基线：

   git fetch upstream
   git rebase upstream/main
   

3. 检查重设基线操作之后的状态：

   git status
   

   你会看到一组存在冲突的文件。

4. 打开每个存在冲突的文件，查找冲突标记：>>>、<<< 和 ===。 解决完冲突之后删除冲突标记。

   说明：

   进一步的详细信息可参见 冲突是怎样表示的.

5. 添加文件到变更集合：

   git add <filename>
   

6. 继续执行基线变更（rebase）操作：

   git rebase --continue
   

7. 根据需要重复步骤 2 到 5。

   在应用完所有提交之后，git status 命令会显示 rebase 操作完成。

8. 将分支强制推送到你的派生仓库：

   git push --force-with-lease origin <your-branch-name>
   

   PR 不再显示存在冲突。

压缩（Squashing）提交

如果你的 PR 包含多个提交（commits），你必须将其压缩成一个提交才能被合并。 你可以在 PR 的 Commits Tab 页面查看提交个数，也可以在本地通过 git log 命令查看提交个数。

1. 启动一个交互式的 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。

2. 开始编辑文件。

   修改原来的文本：

   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 成为时间线中的一部分。

3. 保存文件并退出编辑器。

4. 推送压缩后的提交：

   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 时，务必尽量填充所给的模板，多提供详细信息。

接下来

• 阅读评阅节，学习评阅过程。

2 - 为发行版本撰写功能特性文档

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 和个人、是否该特性需要文档、 该特性的发行说明草稿以及该特性是否已经被合并等等。阅读此清单时请注意：

• Beta 和 Stable 功能特性通常比 Alpha 特性更为需要文档支持。
• 如果某功能特性尚未被合并，就很难测试或者为其撰写文档。 对于对应的 PR 而言，也很难讲特性是否完全实现。
• 确定某个功能特性是否需要文档的过程是一个手动的过程。 即使某个功能特性没有标记需要文档，你仍可能需要为其提供文档。

针对开发人员或其他 SIG 成员

本节中的信息是针对为发行版本中新功能特性撰写文档的来自其他 Kubernetes SIG 的成员。

如果你是某个 SIG 的成员，负责为 Kubernetes 开发某一项新的功能特性，你需要与 SIG Docs 一起工作，确保这一新功能在发行之前已经为之撰写文档。 请参考特性跟踪清单或者 Kubernetes Slack 上的 #sig-release 频道，检查时间安排的细节以及截止日期。

提交占位 PR

1. 在 kubernetes/website 仓库上针对 dev-1.33 分支提交一个draft PR，其中包含较少的、待以后慢慢补齐的提交内容。 要创建一个草案（draft）状态的 PR，可以在 Create Pull Request 下拉菜单中选择 Create Draft Pull Request，然后点击 Draft Pull Request。
2. 编辑拉取请求描述以包括指向 kubernetes/kubernetes PR 和 kubernetes/enhancements 问题的链接。
3. 在对应的 kubernetes/enhancements issue 上添加评论，附上新 PR 的链接以便管理此发行版本的人员能够得到通知， 了解特性的文档正在被撰写，在新的发行版本中要跟踪其进展。

如果对应的功能特性不需要任何类型的文档变更，请通过在 #sig-release Slack 频道声明这一点以确保 sig-release 团队了解。 如果功能特性确实需要文档，而没有对应的 PR 提交，该功能特性可能会被从里程碑中移除。

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/ 目录中为其创建一个特性门控文件。 此文件的名称应该是特性门控的名称，此名称的式样从 UpperCamelCase 转换为 kebab-case，并以 .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 均经过评审且合并就绪

如果你的 PR 在发行截止日期之前尚未合并到 dev-1.33 分支， 请与负责管理该发行版本的文档团队成员一起合作，在截止期限之前将其合并。 如果功能特性需要文档，而文档并未就绪，该特性可能会被从里程碑中去除。

3 - 提交博客和案例分析

任何人都可以撰写博客并提交评阅。 案例分析则在被批准之前需要更多的评阅。

Kubernetes 博客

Kubernetes 博客用于项目发布新功能特性、 社区报告以及其他一些可能对整个社区很重要的新闻。 其读者包括最终用户和开发人员。 大多数博客的内容是关于核心项目中正在发生的事情， 不过我们也鼓励你提交一些有关生态系统中其他时事的博客。

任何人都可以撰写博客并提交评阅。

提交博文

博文不应该是商业性质的，应该包含广泛适用于 Kubernetes 社区的原创内容。 合适的博客内容包括：

• Kubernetes 新能力
• Kubernetes 项目更新信息
• 来自特别兴趣小组（Special Interest Groups, SIG）的更新信息
• 教程和演练
• 有关 Kubernetes 的纲领性理念
• Kubernetes 合作伙伴 OSS 集成信息
• 仅限原创内容

不合适的博客内容包括：

• 供应商产品推介
• 不含集成信息和客户故事的合作伙伴更新信息
• 已发表的博文（可刊登博文译稿）

要提交博文，你可以遵从以下步骤：

1. 如果你还未签署 CLA，请先签署 CLA。
2. 查阅网站仓库中现有博文的 Markdown 格式。
3. 在你所选的文本编辑器中撰写你的博文。
4. 在第 2 步的同一链接上，点击 Create new file 按钮。 将你的内容粘贴到编辑器中。为文件命名，使其与提议的博文标题一致， 但不要在文件名中写日期。 博客评阅者将与你一起确定最终的文件名和发表博客的日期。
5. 保存文件时，GitHub 将引导你完成 PR 流程。
6. 博客评阅者将评阅你提交的内容，并与你一起处理反馈和最终细节。 当博文被批准后，博客将排期发表。

指导原则和期望

• 博客内容不可以是销售用语。
  • 文章内容必须是对整个 Kubernetes 社区中很多人都有参考意义。 例如，所提交的文章应该关注上游的 Kubernetes 项目本身，而不是某个厂商特定的配置。 请参阅文档风格指南 以了解哪些内容是 Kubernetes 所允许的。
  • 链接应该主要指向官方的 Kubernetes 文档。 当引用外部信息时，链接应该是多样的。 例如，所提交的博客文章中不可以只包含指向某个公司的博客的链接。
  • 有些时候，这是一个比较棘手的权衡过程。 博客团队的存在目的即是为 Kubernetes 博客提供文章是否合适的指导意见。 所以，需要帮助的时候不要犹豫。

• 博客内容并非在某特定日期发表。
  • 文章会交由社区自愿者评阅。我们会尽力满足特定的时限要求，只是无法就此作出承诺。
  • Kubernetes 项目的很多核心组件会在发布窗口期内提交博客文章，导致发表时间被推迟。 因此，请考虑在发布周期内较为平静的时间段提交博客文章。
  • 如果你希望就博文发表日期上进行较大范围的协调，请联系 CNCF 推广团队。 这也许是比提交博客文章更合适的一种选择。
  • 有时，博客的评审可能会堆积起来。如果你觉得你的文章没有引起该有的重视，你可以通过 #sig-docs-blog Slack 频道联系博客团队， 以获得实时反馈。

• 博客内容应该对 Kubernetes 用户有用。
  • 与参与 Kubernetes SIG 活动相关，或者与这类活动的结果相关的主题通常是切题的。 请参考 贡献者沟通（Contributor Comms）团队的工作以获得对此类博文的支持。
  • Kubernetes 的组件都有意设计得模块化，因此使用类似 CNI、CSI 等集成点的工具通常都是切题的。
  • 关于其他 CNCF 项目的博客可能切题也可能不切题。 我们建议你在提交草稿之前与博客团队联系。
    • 很多 CNCF 项目有自己的博客。这些博客通常是更好的选择。 有些时候，某个 CNCF 项目的主要功能特性或者里程碑的变化可能是用户有兴趣在 Kubernetes 博客上阅读的内容。
  • 关于为 Kubernetes 项目做贡献的博客内容应该放在 Kubernetes 贡献者站点上。

• 博客文章须是原创内容。
  • 官方博客的目的不是将某第三方已发表的内容重新作为新内容发表。
  • 博客的授权协议 的确允许出于商业目的来使用博客内容；但并不是所有可以商用的内容都适合在这里发表。
• 博客文章的内容应该在一段时间内不过期。
  • 考虑到项目的开发速度，我们希望读者看到的是不必更新就能保持长期准确的内容。
  • 有时候，在官方文档中添加一个教程或者进行内容更新都是比博客更好的选择。
    • 可以考虑在博客文章中将较长技术内容的重点放在鼓励读者自行尝试上， 或者放在问题域本身或者为什么读者应该关注某个话题上。

提交博客的技术考虑

所提交的内容应该是 Markdown 格式的，以便能够被 Hugo 生成器来处理。 关于如何使用相关技术，有很多可用的资源。

对于插图、表格或图表，可以使用 figure shortcode。 对于其他图片，我们强烈建议使用 alt 属性；如果一张图片不需要任何 alt 属性， 那么这张图片在文章中就不是必需的。

我们知道这一需求可能给那些对此过程不熟悉的朋友们带来不便， 我们也一直在寻找降低难度的解决方案。 如果你有降低难度的好主意，请自荐帮忙。

SIG Docs 博客子项目负责管博客的评阅过程。 更多信息可参考提交博文。

要提交博文，你可以遵从以下指南：

• 发起一个包含新博文的 PR。 新博文要创建于 content/en/blog/_posts 目录下。

• 确保你的博文遵从合适的命名规范，并带有下面的引言（元数据）信息：

  • Markdown 文件名必须符合格式 YYYY-MM-DD-Your-Title-Here.md。 例如，2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md。

  • 不要在文件名中包含多余的句点。类似 2020-01-01-whats-new-in-1.19.md 这类文件名会导致文件无法正确打开。

  • 引言部分必须包含以下内容：

    ---
    layout: blog
    title: "Your Title Here"
    date: YYYY-MM-DD
    slug: text-for-URL-link-here-no-spaces
    ---
    author: >
      Author-1 (Affiliation),
      Author-2 (Affiliation),
      Author-3 (Affiliation)  
    

  • 第一个或者最初的提交的描述信息中应该包含一个所作工作的简单摘要， 并作为整个博文的一个独立描述。 请注意，对博文的后续修改编辑都会最终合并到此主提交中，所以此提交的描述信息 应该尽量有用。
    • 较好的提交消息（Commit Message）示例：
      • Add blog post on the foo kubernetes feature
      • blog: foobar announcement
    • 较差的提交消息示例：
      • Add blog post
      • .
      • initial commit
      • draft post
  • 博客团队会对 PR 内容进行评阅，为你提供一些评语以便修订。 之后，机器人会将你的博文合并并发表。
  • 如果博文的内容仅包含预期无需更新就能对读者保持精准的内容， 则可以将这篇博文标记为长期有效（evergreen）， 且免除添加博文发表一年后内容过期的自动警告。

    • 要将一篇博文标记为长期有效，请在引言部分添加以下标记：

      evergreen: true
      

    • 不应标记为长期有效的内容示例：

      • 仅适用于特定发行版或版本而不是所有未来版本的教程
      • 对非正式发行（Pre-GA）API 或功能特性的引用

制作 Kubernetes 贡献者博客的镜像

要从 Kubernetes 贡献者博客制作某篇博文的镜像，遵循以下指导原则：

• 保持博客内容不变。如有变更，应该先在原稿上进行更改，然后再更改到镜像的文章上。
• 镜像博客应该有一个 canonicalUrl，即基本上是原始博客发布后的网址。
• 与 Kubernetes 贡献者博客相同，Kubernetes 博客文章也按照新指南在 YAML 标头中提及作者。应确保这一点。
• 发布日期与原博客保持一致。

在制作镜像博客时，你也需遵守本文所述的所有其他指导原则和期望。

提交案例分析

案例分析用来概述组织如何使用 Kubernetes 解决现实世界的问题。 Kubernetes 市场化团队和 CNCF 成员会与你一起工作， 撰写所有的案例分析。

请查看现有案例分析的源码。

参考案例分析指南， 根据指南中的注意事项提交你的 PR 请求。