贡献上游 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 仓库创建拉取请求。通常，这涉及创建仓库的分支 (fork)。更多信息，请参见创建拉取请求和GitHub 标准的分支 (Fork) 和拉取请求 (Pull Request) 工作流程。

全局概览

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

当你在生成的文档中看到 Bug 时，可以考虑在上游项目中创建一个补丁来修复它。

克隆 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 规范和相关文件。请保持这两次提交分开。也就是说，不要压缩（squash）你的提交。

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

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

将你的提交拣选（Cherry Pick）到发布分支

在前一节中，你在 master 分支中编辑了一个文件，然后运行脚本生成了 OpenAPI 规范和相关文件。接着，你将你的更改作为拉取请求提交到了 kubernetes/kubernetes 仓库的 master 分支。现在假设你想将你的更改回迁（backport）到发布分支。例如，假设 master 分支用于开发 Kubernetes 1.33 版本，而你想将更改回迁到 release-1.32 分支。

回顾一下，你的拉取请求包含两次提交：一次用于编辑 types.go，另一次用于脚本生成的文件。下一步是提议将你的第一次提交拣选（Cherry Pick）到 release-1.32 分支。其思路是拣选编辑 types.go 的提交，而不是包含运行脚本结果的提交。有关说明，请参见提议拣选（Cherry Pick）。

当你准备好一个拉取请求，用于将你的那一次提交拣选到 release-1.32 分支时，下一步是在你本地环境的 release-1.32 分支中运行这些脚本。

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

现在向你的拣选（Cherry Pick）拉取请求添加一个包含最新生成的 OpenAPI 规范和相关文件的提交。监控你的拉取请求，直到它合并到 release-1.32 分支。

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

生成发布的参考文档

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

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

下一步

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