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

返回本页常规视图.

贡献新内容

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

flowchart LR subgraph second[开始之前] direction TB S[ ] -.- A[签署 CNCF CLA] --> B[选择 Git 分支] B --> C[每个 PR 一种语言] C --> F[检查贡献者工具] end subgraph first[基本知识] direction TB T[ ] -.- D[用 markdown 编写文档
并用 Hugo 构建网站] --- E[GitHub 源代码] E --- G['/content/../docs' 文件夹包含
多语言文档] G --- H[评审 Hugo 页面内容
类型和短代码] end first ----> second classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,B,C,D,E,F,G,H grey class S,T spacewhite class first,second white

插图 - 贡献新内容准备工作

上图描述了你在提交新内容之前需要知晓的信息。 详细信息见下文。

基本知识

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

开始之前

签署 CNCF CLA

所有 Kubernetes 贡献者必须阅读贡献者指南签署贡献者授权同意书 (Contributor License Agreement, CLA)

若贡献者尚未签署 CLA,其发起的 PR 将无法通过自动化测试。 你所提供的姓名和邮件地址必须与 git config 中配置的完全相同, 而且你的 git 用户名和邮件地址必须与用来签署 CNCF CLA 的信息一致。

选择要使用的 Git 分支

在发起 PR 时,你需要预先知道基于哪个分支来开展工作。

场景分支
针对当前发行版本的,对现有英文内容的修改或新的英文内容main
针对功能特性变更的内容分支对应于功能特性变更的主要和次要版本,分支名称采用 dev-<version> 的模式。例如,如果某功能特性在 v1.25 版本发生变化,则对应的文档变化要添加到 dev-1.25 分支。
其他语言的内容(本地化)基于本地化团队的约定。参见本地化分支策略了解更多信息。

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

每个 PR 牵涉的语言

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

为贡献者提供的工具

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

1 - 发起拉取请求(PR)

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

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

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

使用 GitHub 提交变更

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

flowchart LR A([fa:fa-user 新的
贡献者]) --- id1[(K8s/Website
GitHub)] subgraph tasks[使用 GitHub 提交变更] direction TB 0[ ] -.- 1[1. 编辑此页] --> 2[2. 使用 GitHub markdown
编辑器进行修改] 2 --> 3[3. 填写 Propose file change] end subgraph tasks2[ ] direction TB 4[4. 选择 Propose file change] --> 5[5. 选择 Create pull request] --> 6[6. 填写 Open a pull request] 6 --> 7[7. 选择 Create pull request] end id1 --> tasks --> tasks2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,1,2,3,4,5,6,7 grey class 0 spacewhite class tasks,tasks2 white class id1 k8s

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

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

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

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

  1. 选择 Propose File Change

  2. 选择 Create pull request

  3. 出现 Open a pull request 界面。填写表单:

    • Subject 字段默认为提交的概要信息。你可以根据需要修改它。
    • Body 字段包含更为详细的提交消息,如果你之前有填写过的话, 以及一些模板文字。填写模板所要求的详细信息, 之后删除多余的模板文字。
    • 确保 Allow edits from maintainers 复选框被勾选。
  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 的带用户界面的应用。

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

flowchart LR 1[派生 K8s/website
仓库] --> 2[创建本地克隆副本
并指定 upstream 仓库] subgraph changes[你的变更] direction TB S[ ] -.- 3[创建一个分支
例如: my_new_branch] --> 3a[使用文本编辑器
进行修改] --> 4["使用 Hugo 在本地
预览你的变更
(localhost:1313)
或构建容器镜像"] end subgraph changes2[提交 / 推送] direction TB T[ ] -.- 5[提交你的变更] --> 6[将提交推送到
origin/my_new_branch] end 2 --> changes --> changes2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class 1,2,3,3a,4,5,6 grey class S,T spacewhite class changes,changes2 white

图 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
    
  1. 前往新的 website 目录,将 kubernetes/website 仓库设置为 upstream 远端:

    cd website
    
    git remote add upstream https://github.com/kubernetes/website.git
    
  1. 确认你现在有两个仓库,originupstream

    git remote -v
    

    Output is similar to:

    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/main 分支,从 kubernetes/website 取回 upstream/main

    git fetch origin
    git fetch upstream
    

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

创建一个分支

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

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

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

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

    git checkout -b <my_new_branch> upstream/main
    
  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"
    
  1. 推送你本地分支及其中的新提交到你的远程派生副本库:

    git push origin <my_new_branch>
    

在本地预览你的变更

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

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

  1. 在本地构建容器镜像 如果你正在测试对 Hugo 工具本身的更改,则仅需要此步骤

    # 在终端窗口中执行(如果有需要)
    make container-image
    
  1. 在容器中启动 Hugo:

    # 在终端窗口中执行
    make container-serve
    
  1. 启动浏览器,浏览 https://localhost:1313。 Hugo 会监测文件的变更并根据需要重新构建网站。

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

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

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

  2. 如果你尚未更新你的网站仓库,则 website/themes/docsy 目录是空的。 如果本地缺少主题的副本,则该站点无法构建。 要更新网站主题,运行以下命令:

git submodule update --init --recursive --depth 1
  1. 启动一个终端窗口,进入 Kubernetes 网站仓库目录,启动 Hugo 服务器:

    cd <path_to_your_repo>/website
    hugo server --buildFuture
    
  1. 在浏览器的地址栏输入: https://localhost:1313。 Hugo 会监测文件的变更并根据需要重新构建网站。

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

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

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

flowchart LR subgraph first[ ] direction TB 1[1. 前往 K8s/website 仓库] --> 2[2. 选择 New Pull Request] 2 --> 3[3. 选择 compare across forks] 3 --> 4[4. 从 head repository 下拉菜单
选择你的克隆副本] end subgraph second [ ] direction TB 5[5. 从 compare 下拉菜单
选择你的分支] --> 6[6. 选择 Create Pull Request] 6 --> 7[7. 为你的 PR
添加一个描述] 7 --> 8[8. 选择 Create pull request] end first --> second classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold class 1,2,3,4,5,6,7,8 grey class first,second white

图 3. 从你的克隆副本向 K8s/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 #12345Closes #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 测试。

来自评阅人的修改

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

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

    git fetch origin
    git rebase origin/<your-branch-name>
    
  1. 变更基线(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>
    
  1. kubernetes/websiteupstream/main 分支取回更改,然后重设本地分支的基线:

    git fetch upstream
    git rebase upstream/main
    
  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)提交

如果你的 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 就可以改变重设基线操作之后提交的状态。

    就重设基线操作本身,我们关注 squashpick 选项。

  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 17d54e15ee Address feedback 2d875112ca 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.mdCONTRIBUTING.mdcode-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 SIGs 的成员。

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

提交占位 PR

  1. kubernetes/website 仓库上针对 dev-1.25 分支提交一个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.25 分支, 请与负责管理该发行版本的文档团队成员一起合作,在截止期限之前将其合并。 如果功能特性需要文档,而文档并未就绪,该特性可能会被从里程碑中去除。

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 推广团队。 这也许是比提交博客文章更合适的一种选择。
    • 有时,博客的评审可能会堆积起来。如果你觉得你的文章没有引起该有的重视, 你可以通过此 Slack 频道 联系博客团队,以获得实时反馈。
  • 博客内容应该对 Kubernetes 用户有用。
    • 与参与 Kubernetes SIGs 活动相关,或者与这类活动的结果相关的主题通常是切题的。 请参考上游推广团队的工作以获得对此类博文的支持。
    • Kubernetes 的组件都有意设计得模块化,因此使用类似 CNI、CSI 等集成点的工具 通常都是切题的。
    • 关于其他 CNCF 项目的博客可能切题也可能不切题。 我们建议你在提交草稿之前与博客团队联系。
      • 很多 CNCF 项目有自己的博客。这些博客通常是更好的选择。 有些时候,某个 CNCF 项目的主要功能特性或者里程碑的变化可能是用户有兴趣在 Kubernetes 博客上阅读的内容。
    • 关于为 Kubernetes 项目做贡献的博客内容应该放在 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 内容进行评阅,为你提供一些评语以便修订。 之后,机器人会将你的博文合并并发表。
  • 如果博文的内容仅包含预期无需更新就能对读者保持精准的内容, 则可以将这篇博文标记为长期有效(evergreen), 且免除添加博文发表一年后内容过期的自动警告。
    • 要将一篇博文标记为长期有效,请在引言部分添加以下标记:

      evergreen: true
      
    • 不应标记为长期有效的内容示例:

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

提交案例分析

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

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

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