为上游 Kubernetes 代码做贡献

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

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

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

准备工作

• 您需要安装以下工具

  • Git
  • 版本 1.13+ 的 Golang
  • 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.32，并且您想将更改反向移植到 release-1.31 分支。

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

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

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

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

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

生成已发布的参考文档

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

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

后续步骤

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