为 Kubernetes 文档做贡献

Edit This Page

为上游 Kubernetes 代码库做出贡献

此页面描述如何为上游 kubernetes/kubernetes 项目做出贡献,如修复 Kubernetes API 文档或 kube-* 组件(例如 kube-apiserver、kube-controller-manager 等)中发现的错误。

相反,如果您想从上游代码重新生成 Kubernetes API 或 kube-* 组件的参考文档。请参考以下说明:

准备开始

您需要安装以下工具:

必须设置 $GOPATH 环境变量,并且 etcd 的位置必须在 $PATH 环境变量中。

您需要知道如何创建对 GitHub 代码仓库的拉取请求(Pull Request)。 通常,这涉及创建代码仓库的分支。要获取更多的信息请参考创建 PRGitHub 标准 Fork 和 PR 工作流程

基本原则

Kubernetes API 和 kube-* 组件(例如 kube-apiserverkube-controller-manager)的参考文档是根据上游 Kubernetes 中的源代码自动生成的。

当您在生成的文档中看到错误时,您可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。

克隆 Kubernetes 代码仓库

如果您还没有 kubernetes/kubernetes 代码仓库,请立即参照下列命令获取:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

确定您的 kubernetes/kubernetes 代码仓库克隆的基本目录。 例如,如果按照前面的步骤获取代码仓库,则您的基本目录为 $GOPATH/src/github.com/kubernetes/kubernetes。 接下来其余步骤将您的基本目录称为 <k8s-base> 确定您的 kubernetes-sigs/reference-docs 代码仓库克隆的基本目录。 例如,如果按照前面的步骤获取代码仓库,则您的基本目录为 $GOPATH/src/github.com/kubernetes-sigs/reference-docs。 接下来其余步骤将您的基本目录称为 <rdocs-base>

编辑 Kubernetes 源代码

Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的,该规范是从 Kubernetes 源代码生成的。如果要更改 API 参考文档,第一步是更改 Kubernetes 源代码中的一个或多个注释。

kube-* 组件的文档也是从上游源代码生成的。您必须更改与要修复的组件相关的代码,才能修复生成的文档。

更改上游 Kubernetes 源代码

注意: 以下步骤仅作为示例,不是一般步骤,具体情况因您而异。

以下在 Kubernetes 源代码中编辑注释的示例。

在您本地的 kubernetes/kubernetes 代码仓库中,切换出本地 master 分支,并确保它是最新的:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

假设 master 分支中的此源文件的拼写错误为 “atmost”:

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

在您的本地环境中,打开 types.go 文件,然后将 “atmost” 更改为 “at most”。

以下命令查看您已更改的文件:

git status

输出显示您在 master 分支上,types.go 源文件已被修改:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

提交已编辑的文件

运行 git addgit commit 命令提交到目前为止所做的更改。在下一步中,您将进行第二次提交,将更改分成两个提交很重要。

生成 OpenAPI 规范和相关文件

进入 <k8s-base> 目录并运行以下脚本:

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

运行 git status 命令查看生成的东西。

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

查看 api/openapi-spec/swagger.json 的内容,以确保 typo 已经被修正。例如,您可以运行 git diff -a api/openapi-spec/swagger.json 命令。这很重要,因为 swagger.json 是文档生成过程中第二阶段的输入。

运行 git addgit commit 命令来提交您的更改。现在您有两个提交: 一种包含编辑的 types.go 文件,另一种包含生成的 OpenAPI 规范和相关文件。 将这两个提交分开独立。也就是说,不要 squash 您的提交。

将您的更改作为 PR 提交到 kubernetes/kubernetes 代码仓库的 master 分支。关注您的 PR,并根据需要回复 reviewer 的评论。继续关注您的 PR,直到 PR 被合并为止。

PR 57758 是修复 Kubernetes 源代码中的拼写错误的拉取请求的示例。

注意: 确定要更改的正确源文件可能很棘手。在前面的示例中,官方的源文件位于 kubernetes/kubernetes 代码仓库的 staging 目录中。但是根据您的情况,staging 目录可能不是找到官方源文件的地方。根据指导原则,请检查 kubernetes/kubernetes 代码仓库和相关代码仓库(例如 kubernetes/apiserver)中的 README 文件。

Cherry Pick 将您的提交纳入发布分支

在上一节中,您在 master 分支中编辑了一个文件,然后运行了脚本用来生成 OpenAPI 规范和相关文件。然后将您的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支的 pull request 中。 现在,需要将您的更改反向移植到已经 release 的分支。例如,假设使用 master 分支来开发 Kubernetes 1.10 版,并且您想将更改反向移植到 release-1.9 分支。

回想一下,您的 pull request 有两个提交:一个用于编辑 types.go,一个用于由脚本生成的文件。下一步的目的是对您的第一次提交 cherry pick 到 release-1.9 分支。这个想法是 cherry pick 编辑了 types.go 的提交,但不是具有运行脚本结果的提交。有关说明,请参见提出 Cherry Pick

注意: 提出 cherry pick 要求您有权在 pull request 中设置标签和里程碑。如果您没有这些权限,则需要与可以为您设置标签和里程碑的人员合作。

当您提出一个 pull request,希望将您的一个提交 cherry pick 到 release-1.9 分支中时,下一步是在本地环境的 release-1.9 分支中运行这些脚本。

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

现在将提交添加到您的 Cherry-pick pull request 中,该请求具有最近生成的 OpenAPI 规范和相关文件。关注您的 pull request 请求,直到其合并到 release-1.9 分支中为止。

此时,master 分支和 release-1.9 分支都具有更新的 types.go 文件和一组生成的文件,这些文件反映了您对 types.go 所做的更改。请注意,生成的 OpenAPI 规范和其他 release-1.9 分支中生成的文件不一定与 master 分支中生成的文件相同。release-1.9 分支中生成的文件仅包含来自 Kubernetes 1.9 的 API 元素。master 分支中生成的文件可能包含不在 1.9 中但正在为 1.10 开发的 API 元素。

生成已发布的参考文档

上一节显示了如何编辑源文件然后生成多个文件,包括在 kubernetes/kubernetes 代码仓库中的 api/openapi-spec/swagger.jsonswagger.json 文件是 OpenAPI 定义文件,可用于生成 API 参考文档。

现在,您可以按照生成 Kubernetes API 的参考文档指南来生成 已发布的 Kubernetes API 参考文档

接下来

反馈