这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

贡献新内容

1 - 贡献新内容概述

本节包含贡献新内容之前你需要知晓的一些信息。

基本知识

  • 使用 Markdown 来编写 Kubernetes 文档并使用 Hugo 来构建网站
  • 源代码位于 GitHub 仓库中。 你可以在 /content/en/docs/ 目录下找到 Kubernetes 文档。 某些参考文档是使用位于 update-imported-docs/ 目录下的脚本自动生成的。
  • 页面内容类型使用 Hugo 描述文档内容的表现。
  • 除了基本的 Hugo 短代码（shortcodes）外，我们还在文档中使用一些 定制的 Hugo 短代码以控制内容的表现。
  • 文档的源代码有多种语言形式，位于/content/ 目录下。 每种语言都有自己的由两个字母代表的目录，这两个字母是基于 ISO 639-1 标准来确定的。 例如，英语文档源码位于/content/en/docs/ 目录下。
  • 关于在多种语言中为文档做贡献的详细信息，以及如何启动一种新的语言翻译， 可参考本地化文档。

开始之前

签署 CNCF CLA

所有 Kubernetes 贡献者 必须 阅读 贡献者指南 并签署贡献者授权同意书（Contributor License Agreement，CLA）。

来自尚未签署 CLA 的贡献者的 PR 无法通过自动化服务的测试。 你所提供的姓名和邮件地址必须与 git config 中所找到的完全相同， 而且你的 git 用户名和邮件地址必须与用来签署 CNCF CLA 的一致。

选择要使用的分支

在发起拉取请求时，你需要预先知道要基于哪个分支来开展工作。

场景分支
针对当前发行版本的，对现有英文内容的修改或新的英文内容master
针对功能特性变更的内容功能特性所对应的版本所对应的分支，分支名字模式为 dev-<version>。例如，如果某功能特性在 v1.26 版本发生变化，则对应的文档变化要添加到 dev-1.26 分支。
其他语言的内容（本地化）基于本地化团队的约定。参见本地化分支策略了解更多信息。

如果你仍不能确定要选择哪个分支，请在 #sig-docs Slack 频道上提问。

说明： 如果你已经提交了你的 PR，并且你发现所针对的分支选错了，你（且只能是你）可以重新选择分支。

每个 PR 牵涉的语言

请限制每个 PR 仅涉及一种语言。 如果你需要对多种语言下的同一代码示例进行相同的修改，也请为每种语言发起一个独立的 PR。

为贡献者提供的工具

kubernetes/website 仓库的 文档贡献者工具 目录中包含了一些工具，能够助你的贡献过程更为顺畅。

2 - 发起拉取请求（PR）

说明： 代码开发者们：如果你在为下一个 Kubernetes 发行版本中的某功能特性 撰写文档，请参考为新功能撰写文档。

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

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

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

使用 GitHub 提交变更

如果你在 git 工作流方面欠缺经验，这里有一种发起拉取请求的更为简单的方法。

  1. 在你发现问题的网页，选择右上角的铅笔图标。你也可以滚动到页面底端，选择 编辑此页面。

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

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

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

  1. 选择 Propose File Change.

  2. 选择 Create pull request.

  3. 在 Open a pull request 屏幕上填写表单：

    • Subject 字段默认为提交的概要信息。你可以根据需要修改它。
    • Body 字段包含更为详细的提交消息，如果你之前有填写过的话，以及一些模板文字。 填写模板所要求的详细信息，之后删除多余的模板文字。
    • 确保 Allow edits from maintainers 复选框被勾选。
    说明： PR 描述信息是帮助 PR 评阅人了解你所提议的变更的重要途径。 更多信息请参考发起一个 PR.
  1. 选择 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 的带用户界面的应用。

派生 kubernetes/website 仓库

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

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

  1. 打开终端窗口，克隆你所派生的副本：

    git clone git@github.com/<github_username>/website

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

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

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

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

    git fetch origin
git fetch upstream

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

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

创建一个分支

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

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

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

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

    git checkout -b <my_new_branch> upstream/master
  1. 使用文本编辑器开始构造变更。

在任何时候，都可以使用 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")

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

    git add <your_file_name>

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

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

    git commit -m "Your commit message"
    说明： 不要在提交消息中使用任何 GitHub 关键字。 你可以在后面创建 PR 时使用这些关键字。

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

    git push origin <my_new_branch>

在本地预览你的变更

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

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

说明： 下面的命令中使用 Docker 作为默认的容器引擎。 如果需要重载这一行为，可以设置 CONTAINER_ENGINE。

  1. 在本地构造镜像；

    # 使用 docker (默认)
make container-image

### 或 ###

# 使用 podman
CONTAINER_ENGINE=podman make container-image

  1. 在本地构造了 kubernetes-hugo 镜像之后，可以构造并启动网站：

    # 使用 docker (默认)
make container-serve

### 或 ###

# 使用 podman
CONTAINER_ENGINE=podman make container-serve

  1. 启动浏览器，浏览 https://localhost:1313。 Hugo 会监测文件的变更并根据需要重新构建网站。

  2. 要停止本地 Hugo 实例，可返回到终端并输入 Ctrl+C，或者关闭终端窗口。

另一种方式是，在你的本地计算机上安装并使用 hugo 命令：

  1. 安装 website/netlify.toml 文件中指定的 Hugo 版本。

  2. 启动一个终端窗口，进入 Kubernetes 网站仓库目录，启动 Hugo 服务器：

    cd <path_to_your_repo>/website
hugo server
  1. 在浏览器的地址栏输入： https://localhost:1313。
  2. 要停止本地 Hugo 实例，返回到终端窗口并输入 Ctrl+C 或者关闭终端窗口。

从你的克隆副本向 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：对前一次提交进行增补，而不是创建新的提交

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

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

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

来自评阅人的修改

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

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

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

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

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

合并冲突和重设基线

说明： 要了解更多信息，可参考 Git 分支管理 - 基本分支和合并、 高级合并、 或者在 #sig-docs Slack 频道寻求帮助。

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

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

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

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

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

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

    git fetch upstream
git rebase upstream/master

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

    git status

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

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

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

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

    git add <filename>

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

    git rebase --continue

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

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

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

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

    PR 不再显示存在冲突。

压缩（Squashing）提交

说明： 要了解更多信息，可参看 Git Tools - Rewriting History， 或者在 #sig-docs Slack 频道寻求帮助。

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

说明： 本主题假定使用 vim 作为命令行文本编辑器。

  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。

  1. 开始编辑文件。

    修改原来的文本：

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

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

  2. 推送压缩后的提交：

    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 模版。通过查看一些待解决的 Issues 和 PR，也可以添加对它们的链接。你可以多少了解该团队的流程。 在登记 Issue 或提出 PR 时，务必尽量填充所给的模版，多提供详细信息。

接下来

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

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

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 SIGs 的成员。

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

提交占位 PR

  1. 在 kubernetes/website 仓库上针对 dev-1.26 分支提交一个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 阶段并由某特性门控控制， 请确保在你的 PR 中，该特性门控被添加到 Alpha/Beta 特性门控 表格中。对于新的特性门控选项，需要为该特性门控提供一段描述。 如果所处理的功能特性已经进入正式发布（GA）状态或者被废弃， 请确保将其从上述表格中迁移到 已毕业或废弃的特性 表格中，并确保迁移后保留其 Alpha、Beta 版本变迁历史。

所有 PR 均经过评审且合并就绪

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

4 - 提交博客和案例分析

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

Kubernetes 博客

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

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

指导原则和期望

  • 博客内容不可以是销售用语。
    • 文章内容必须是对整个 Kubernetes 社区中很多人都有参考意义。 例如，所提交的文章应该关注上游的 Kubernetes 项目本身，而不是某个厂商特定的配置。 请参阅文档风格指南 以了解哪些内容是 Kubernetes 所允许的。
    • 链接应该主要指向官方的 Kubernetes 文档。 当引用外部信息时，链接应该是多样的。 例如，所提交的博客文章中不可以只包含指向某个公司的博客的链接。
    • 有些时候，这是一个比较棘手的权衡过程。 博客团队的存在目的即是为 Kubernetes 博客提供文章是否合适的指导意见。 所以，需要帮助的时候不要犹豫。
  • 博客内容并非在某特定日期发表。
    • 文章会交由社区自愿者评阅。我们会尽力满足特定的时限要求，只是无法就此作出承诺。
    • Kubernetes 项目的很多核心组件会在发布窗口期内提交博客文章，导致发表时间被推迟。 因此，请考虑在发布周期内较为平静的时间段提交博文。
    • 如果你希望就博文发表日期上进行较大范围的协调，请联系 CNCF 推广团队。 这也许是比提交博客文章更合适的一种选择。
    • 有时，博客的评审可能会堆积起来。如果你觉得你的文章没有引起该有的重视， 你可以通过此 Slack 频道 联系博客团队，以获得实时反馈。
  • 博客内容应该对 Kubernetes 用户有用。
    • 与参与 Kubernetes SIGs 活动相关，或者与这类活动的结果相关的主题通常是切题的。 请参考上游推广团队的工作以获得对此类博文的支持。
    • Kubernetes 的组件都有意设计得模块化，因此使用类似 CNI、CSI 等集成点的工具 通常都是切题的。
    • 关于其他 CNCF 项目的博客可能切题也可能不切题。 我们建议你在提交草稿之前与博客团队联系。
      • 很多 CNCF 项目有自己的博客。这些博客通常是更好的选择。 有些时候，某个 CNCF 项目的主要功能特性或者里程碑的变化可能是用户有兴趣在 Kubernetes 博客上阅读的内容。
  • 博客文章应该是原创内容。
    • 官方博客的目的不是将某第三方已发表的内容重新作为新内容发表。
    • 博客的授权协议 的确允许出于商业目的来使用博客内容；但并不是所有可以商用的内容都适合在这里发表。
  • 博客文章的内容应该在一段时间内不过期。
    • 考虑到项目的开发速度，我们希望读者看到的是不必更新就能保持长期准确的内容。
    • 有时候，在官方文档中添加一个教程或者进行内容更新都是比博客更好的选择。
      • 可以考虑在博客文章中将较长技术内容的重点放在鼓励读者自行尝试上，或者 放在问题域本身或者为什么读者应该关注某个话题上。

提交博客的技术考虑

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

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

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
---
  • 第一个或者最初的提交的描述信息中应该包含一个所作工作的简单摘要， 并作为整个博文的一个独立描述。 请注意，对博文的后续修改编辑都会最终合并到此主提交中，所以此提交的描述信息 应该尽量有用。
    • 较好的提交消息（Commit Message）示例：
      • Add blog post on the foo kubernetes feature
      • blog: foobar announcement
    • 较差的提交消息示例：
      • Add blog post
      • .
      • initial commit
      • draft post
  • 博客团队会对 PR 内容进行评阅，为你提供一些评语以便修订。 之后，机器人会将你的博文合并并发表。

提交案例分析

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

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

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