为上游 Kubernetes 代码做贡献

此页面介绍如何为上游 kubernetes/kubernetes 项目做贡献。您可以修复 Kubernetes API 文档或 Kubernetes 组件（如 kubeadm、kube-apiserver 和 kube-controller-manager）内容中发现的错误。

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

• 为 Kubernetes API 生成参考文档
• 为 Kubernetes 组件和工具生成参考文档

准备工作

• 您需要安装以下工具

  • Git
  • Golang 版本 1.13+
  • Docker
  • etcd
  • make
  • gcc 编译器/链接器

• 您的 GOPATH 环境变量必须已设置，并且 etcd 的位置必须在您的 PATH 环境变量中。

• 您需要知道如何向 GitHub 仓库创建拉取请求。通常，这涉及创建仓库的分支。有关更多信息，请参阅 创建拉取请求 和 GitHub 标准分支和拉取请求工作流程。

概览

Kubernetes API 和 kube-* 组件（如 kube-apiserver、kube-controller-manager）的参考文档是从 上游 Kubernetes 中的源代码自动生成的。

当您在生成的文档中看到错误时，您可能需要考虑创建一个补丁来在上游项目中修复它。

克隆 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 规范自动生成的，而 OpenAPI 规范是从 Kubernetes 源代码生成的。如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。

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

对上游源代码进行更改

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

在您的本地 kubernetes/kubernetes 仓库中，检出默认分支，并确保它是最新的

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes 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 add 和 git commit 来提交您目前所做的更改。在下一步中，您将进行第二次提交。将您的更改分成两次提交非常重要。

生成 OpenAPI 规范和相关文件

转到 <k8s-base> 并运行以下脚本

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

运行 git status 以查看生成的内容。

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

查看 api/openapi-spec/swagger.json 的内容以确保拼写错误已修复。例如，您可以运行 git diff -a api/openapi-spec/swagger.json。这很重要，因为 swagger.json 是文档生成过程第二阶段的输入。

运行 git add 和 git commit 来提交您的更改。现在您有两个提交：一个包含已编辑的 types.go 文件，另一个包含生成的 OpenAPI 规范和相关文件。请将这两个提交分开。也就是说，不要压缩您的提交。

将您的更改作为 拉取请求 提交到 kubernetes/kubernetes 仓库的 master 分支。监控您的拉取请求，并根据需要回复审查者的评论。继续监控您的拉取请求，直到它被合并。

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

将您的提交挑选到发布分支中

在上一节中，您编辑了 master 分支中的文件，然后运行脚本以生成 OpenAPI 规范和相关文件。然后，您将更改提交到 kubernetes/kubernetes 仓库的 master 分支的拉取请求中。现在假设您想将更改反向移植到发布分支中。例如，假设 master 分支用于开发 Kubernetes 版本 1.30，并且您想将更改反向移植到 release-1.29 分支中。

回想一下，您的拉取请求有两个提交：一个用于编辑 types.go，另一个用于脚本生成的文件。下一步是建议将您的第一个提交挑选到 release-1.29 分支中。我们的想法是挑选编辑 types.go 的提交，而不是包含运行脚本结果的提交。有关说明，请参阅 建议挑选。

当您在 release-1.29 分支中有一个拉取请求来挑选您的一个提交时，下一步是在本地环境的 release-1.29 分支中运行以下脚本。

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

现在，将包含最近生成的 OpenAPI 规范和相关文件的提交添加到您的挑选拉取请求中。监控您的拉取请求，直到它被合并到 release-1.29 分支中。

此时，master 分支和 release-1.29 分支都包含您更新的 types.go 文件以及一组反映您对 types.go 所做更改的生成文件。请注意，release-1.29 分支中生成的 OpenAPI 规范和其他生成文件不一定与 master 分支中生成的相同。release-1.29 分支中生成的文件仅包含 Kubernetes 1.29 中的 API 元素。master 分支中生成的文件可能包含不在 1.29 中但正在为 1.30 开发的 API 元素。

生成已发布的参考文档

上一节介绍了如何编辑源文件，然后生成多个文件，包括 kubernetes/kubernetes 仓库中的 api/openapi-spec/swagger.json。swagger.json 文件是用于生成 API 参考文档的 OpenAPI 定义文件。

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

后续步骤

• 为 Kubernetes API 生成参考文档
• 为 Kubernetes 组件和工具生成参考文档
• 为 kubectl 命令生成参考文档