為上游 Kubernetes 程式碼貢獻
此頁面展示瞭如何為上游的 kubernetes/kubernetes
專案貢獻。你可以修復 Kubernetes API 文件中發現的 bug,或者修復 Kubernetes 元件(如 kubeadm
、kube-apiserver
和 kube-controller-manager
)的內容。
如果你想從上游程式碼重新生成 Kubernetes API 或 kube-*
元件的參考文件,請參閱以下說明
準備工作
您需要安裝以下工具
你的
GOPATH
環境變數必須已設定,並且etcd
的位置必須在你的PATH
環境變數中。你需要知道如何向 GitHub 倉庫建立 pull request。通常,這涉及到建立倉庫的 fork。更多資訊,請參閱 建立 Pull Request 和 GitHub 標準 Fork & Pull Request 工作流程。
整體概覽
Kubernetes API 和 kube-*
元件(如 kube-apiserver
、kube-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 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 規範和相關檔案的生成結果。保持這兩個提交分開。也就是說,不要 squashing 你的提交。
將你的更改作為 pull request 提交到 kubernetes/kubernetes 倉庫的 master 分支。監控你的 pull request,並根據需要響應審閱者的評論。繼續監控你的 pull request,直到它被合併。
PR 57758 是一個修復 Kubernetes 原始碼中拼寫錯誤的 pull request 示例。
注意
確定要修改的正確原始檔可能會很棘手。在前面的示例中,權威原始檔位於kubernetes/kubernetes
倉庫的 staging
目錄中。但在你的情況下,staging
目錄可能不是查詢權威源的地方。有關指導,請檢視 kubernetes/kubernetes 倉庫以及相關倉庫(如 kubernetes/apiserver)中的 README
檔案。將你的提交 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 需要你有許可權在你的 pull request 中設定標籤和里程碑。如果你沒有這些許可權,你需要與擁有這些許可權的人合作。當你有一個用於將你的一個提交 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.json
。swagger.json
檔案是用於生成 API 參考文件的 OpenAPI 定義檔案。
你現在可以遵循 生成 Kubernetes API 參考文件 指南,來生成 已釋出的 Kubernetes API 參考文件。