為上游 Kubernetes 程式碼貢獻

此頁面展示瞭如何為上游的 kubernetes/kubernetes 專案貢獻。你可以修復 Kubernetes API 文件中發現的 bug,或者修復 Kubernetes 元件(如 kubeadmkube-apiserverkube-controller-manager)的內容。

如果你想從上游程式碼重新生成 Kubernetes API 或 kube-* 元件的參考文件,請參閱以下說明

準備工作

整體概覽

Kubernetes API 和 kube-* 元件(如 kube-apiserverkube-controller-manager)的參考文件是從 上游 Kubernetes 的原始碼自動生成的。

當你發現生成文件中的 bug 時,你可能想考慮建立一個 patch 來在專案上游修復它。

克隆 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 addgit commit 來提交你到目前為止所做的更改。在下一步,你將進行第二次提交。將你的更改分成兩個提交非常重要。

轉到 <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 addgit commit 來提交你的更改。現在你有兩個提交:一個包含編輯後的 types.go 檔案,另一個包含 OpenAPI 規範和相關檔案的生成結果。保持這兩個提交分開。也就是說,不要 squashing 你的提交。

將你的更改作為 pull request 提交到 kubernetes/kubernetes 倉庫的 master 分支。監控你的 pull request,並根據需要響應審閱者的評論。繼續監控你的 pull request,直到它被合併。

PR 57758 是一個修復 Kubernetes 原始碼中拼寫錯誤的 pull request 示例。

將你的提交 cherry-pick 到 release 分支

在上一節中,你編輯了一個 master 分支中的檔案,然後執行指令碼生成了 OpenAPI 規範和相關檔案。然後,你將更改提交到了 kubernetes/kubernetes 倉庫的 master 分支的 pull request。現在假設你想將你的更改 backport 到一個 release 分支。例如,假設 master 分支正用於開發 Kubernetes 1.34 版本,而你想將你的更改 backport 到 release-1.33 分支。

回想一下,你的 pull request 有兩個提交:一個用於編輯 types.go,另一個用於執行指令碼生成的檔案。下一步是提議將你的第一個提交 cherry-pick 到 release-1.33 分支。這個想法是 cherry-pick 編輯了 types.go 的提交,但不是包含執行指令碼結果的提交。有關說明,請參閱 提議 Cherry Pick

當你有一個用於將你的一個提交 cherry-pick 到 release-1.33 分支的 pull request 時,下一步是在你的本地環境的 release-1.33 分支中執行這些指令碼。

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

現在,將包含最近生成的 OpenAPI 規範和相關檔案的提交新增到你的 cherry-pick pull request 中。監控你的 pull request,直到它被合併到 release-1.33 分支。

此時,master 分支和 release-1.33 分支都擁有你更新的 types.go 檔案以及反映你對 types.go 所做更改的一組生成檔案。請注意,release-1.33 分支中的生成 OpenAPI 規範和其他生成檔案不一定與 master 分支中的生成檔案相同。release-1.33 分支中的生成檔案僅包含 Kubernetes 1.33 的 API 元素。master 分支中的生成檔案可能包含不屬於 1.33 但正在為 1.34 開發的 API 元素。

生成已釋出的參考文件

前面的部分展示瞭如何編輯原始檔,然後生成幾個檔案,包括 kubernetes/kubernetes 倉庫中的 api/openapi-spec/swagger.jsonswagger.json 檔案是用於生成 API 參考文件的 OpenAPI 定義檔案。

你現在可以遵循 生成 Kubernetes API 參考文件 指南,來生成 已釋出的 Kubernetes API 參考文件

下一步

最後修改時間:2024 年 1 月 2 日下午 8:14 PST:清理三個 generate-ref-docs (4d6a8e57c0)