为上游 Kubernetes 代码库做出贡献

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

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

准备开始

基本说明

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

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

克隆 Kubernetes 代码仓库

如果你还没有 kubernetes/kubernetes 代码仓库，请参照下列命令获取：

  1. mkdir $GOPATH/src
  2. cd $GOPATH/src
  3. 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 代码仓库中，检出默认分支，并确保它是最新的：

  1. cd <k8s-base>
  2. git checkout master
  3. 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”。

以下命令验证你已经更改了文件：

  1. git status

输出显示你在 master 分支上，types.go 源文件已被修改：

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

提交已编辑的文件

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

生成 OpenAPI 规范和相关文件

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

  1. hack/update-generated-swagger-docs.sh
  2. hack/update-openapi-spec.sh
  3. hack/update-generated-protobuf.sh

运行 git status 命令查看生成的文件。

  1. On branch master
  2. ...
  3.     modified:   api/openapi-spec/swagger.json
  4.     modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
  5.     modified:   pkg/generated/openapi/zz_generated.openapi.go
  6.     modified:   staging/src/k8s.io/api/apps/v1/generated.proto
  7.     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 命令来提交你的更改。现在你有两个提交（commits）： 一种包含编辑的 types.go 文件，另一种包含生成的 OpenAPI 规范和相关文件。 将这两个提交分开独立。也就是说，不要 squash 你的提交。

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

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

说明： 确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 kubernetes/kubernetes 代码仓库的 staging 目录中。但是根据你的情况，staging 目录可能不是找到官方源文件的地方。 如果需要帮助，请阅读 kubernetes/kubernetes 代码仓库和相关代码仓库 （例如 kubernetes/apiserver） 中的 README 文件。

将你的提交 Cherrypick 到发布分支

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

回想一下，你的 PR 有两个提交：一个用于编辑 types.go，一个用于由脚本生成的文件。 下一步是将你的第一次提交 cherrypick 到 release-1.25 分支。 这样做的原因是仅 cherrypick 编辑了 types.go 的提交， 而不是具有脚本运行结果的提交。 有关说明，请参见提出 Cherry Pick。

说明： 提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果你没有这些权限， 则需要与可以为你设置标签和里程碑的人员合作。

当你发起 PR 将你的一个提交 cherry pick 到 release-1.25 分支中时， 下一步是在本地环境的 release-1.25 分支中运行如下脚本。

  1. hack/update-generated-swagger-docs.sh
  2. hack/update-openapi-spec.sh
  3. hack/update-generated-protobuf.sh
  4. hack/update-api-reference-docs.sh

现在将提交添加到你的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。 关注你的 PR，直到其合并到 release-1.25 分支中为止。

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

生成已发布的参考文档

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

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

接下来