为上游 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/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 源代码中错字的拉取请求示例。

将您的提交 cherry-pick 到发布分支

在上一节中，您编辑了 master 分支中的文件，然后运行脚本以生成多个文件，包括 kubernetes/kubernetes 存储库中的 api/openapi-spec/swagger.json。swagger.json 文件是用于生成 API 参考文档的 OpenAPI 定义文件。

现在假设您想将您的更改 backport 到发布分支。例如，假设 master 分支用于开发 Kubernetes 版本 1.31，并且您想将您的更改 backport 到 release-1.30 分支。

建议 Cherry Pick 要求您有权在您的拉取请求中设置标签和里程碑。如果您没有这些权限，您将需要与可以为您设置标签和里程碑的人员合作。

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

当您有一个拉取请求用于将您的一个提交 cherry-pick 到 release-1.30 分支时，下一步是在本地环境的 release-1.30 分支中运行这些脚本。

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

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

生成发布的参考文档

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

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

• 为 Kubernetes API 生成参考文档
• 下一步
• 为 kubectl 命令生成参考文档