本节包含你在贡献新内容之前需要知晓的信息。
新内容的任务流程 {#new-content-task-flow}
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 编写文档<br>并用 Hugo 构建网站] --- E[GitHub 源代码] E --- G['/content/../docs' 文件夹包含<br>多语言文档] G --- H[评审 Hugo 页面内容<br>类型和短代码] 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
插图 - 贡献新内容准备工作
上图描述了你在提交新内容之前需要知晓的信息。 详细信息见下文。
基本知识 {#contributing-basics}
-
使用 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/目录下。 -
关于为多语言文档做贡献以及如何开始新翻译的详细信息, 可参考本地化文档。
开始之前 {#before-you-begin}
签署 CNCF CLA {#sign-the-cla}
所有 Kubernetes 贡献者必须阅读贡献者指南 并签署贡献者授权同意书 (Contributor License Agreement, CLA)。
若贡献者尚未签署 CLA,其发起的 PR 将无法通过自动化测试。
你所提供的姓名和邮件地址必须与 git config 中配置的完全相同,
而且你的 Git 用户名和邮件地址必须与用来签署 CNCF CLA 的信息一致。
选择要使用的 Git 分支 {#choose-which-git-branch-to-use}
在发起 PR 时,你需要预先知道基于哪个分支来开展工作。
| 场景 | 分支 |
|---|---|
| 针对当前发行版本的,对现有英文内容的修改或新的英文内容 | main |
| 针对功能特性变更的内容 | 分支对应于功能特性变更的主要和次要版本,分支名称采用 dev-<version> 的模式。例如,如果某功能特性在 v 版本发生变化,则对应的文档变化要添加到 dev- 分支。 |
| 其他语言的内容(本地化) | 基于本地化团队的约定。参见本地化分支策略了解更多信息。 |
如果你仍不能确定要选择哪个分支,请在 Slack 的 #sig-docs 频道上提出问题。
如果你已经提交了 PR,并且发现所针对的分支选错了,你(且只有作为提交人的你)可以更改分支。
每个 PR 牵涉的语言 {#languages-per-pr}
请确保每个 PR 仅涉及一种语言。 如果你需要对多种语言下的同一代码示例进行相同的修改,也请为每种语言发起一个独立的 PR。
为贡献者提供的工具 {#tools-for-contributors}
kubernetes/website 仓库的文档贡献者工具目录中包含了一些工具,
有助于使你的贡献过程更为顺畅。
来源:Kubernetes 文档贡献者 · 作者与贡献记录 · CC BY 4.0。离线整理了版式、链接和媒体显示。
