貢獻程式碼至上游 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 儲存庫建立提取請求。通常，這會涉及建立儲存庫的分支。如需更多資訊，請參閱 建立提取請求 和 GitHub 標準 Fork & Pull Request 工作流程。

概觀

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 規格和相關檔案。保持這兩個提交分開。也就是說，不要合併你的提交。

將你的變更以提取請求 (pull request) 的形式提交到 kubernetes/kubernetes 儲存庫的 master 分支。監控你的提取請求，並根據需要回覆審閱者的評論。持續監控你的提取請求直到它被合併。

PR 57758 是一個在 Kubernetes 原始碼中修正錯字的提取請求範例。

將你的提交揀選 (cherry pick) 到發行分支

在前面的章節中，你編輯了 master 分支中的檔案，然後執行腳本以產生 OpenAPI 規格和相關檔案。然後你將你的變更以提取請求的形式提交到 kubernetes/kubernetes 儲存庫的 master 分支。現在假設你想將你的變更向後移植到發行分支。例如，假設 master 分支正用於開發 Kubernetes 1.32 版本，而你想將你的變更向後移植到 release-1.31 分支。

回想一下，你的提取請求有兩個提交：一個用於編輯 types.go，另一個用於腳本產生的檔案。下一步是建議將你的第一個提交揀選到 release-1.31 分支。想法是揀選編輯 types.go 的提交，而不是包含執行腳本結果的提交。有關說明，請參閱 Propose a Cherry Pick。

當你準備好將一個提交揀選到 release-1.31 分支的提取請求時，下一步是在你的本機環境的 release-1.31 分支中執行這些腳本。

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

現在為你的揀選提取請求新增一個提交，其中包含最近產生的 OpenAPI 規格和相關檔案。監控你的提取請求，直到它被合併到 release-1.31 分支中。

此時，master 分支和 release-1.31 分支都擁有你更新後的 types.go 檔案和一組反映你對 types.go 所做變更的產生檔案。請注意，release-1.31 分支中產生的 OpenAPI 規格和其他產生檔案不一定與 master 分支中的產生檔案相同。release-1.31 分支中產生的檔案僅包含 Kubernetes 1.31 的 API 元素。master 分支中產生的檔案可能包含不在 1.31 中，但正在為 1.32 開發的 API 元素。

產生發布的參考文件

前面的章節展示了如何編輯原始碼檔案，然後產生多個檔案，包括 kubernetes/kubernetes 儲存庫中的 api/openapi-spec/swagger.json。swagger.json 檔案是用於產生 API 參考文件的 OpenAPI 定義檔案。

你現在可以依照 產生 Kubernetes API 的參考文件 指南來產生已發布的 Kubernetes API 參考文件。

下一步

• 為 Kubernetes API 產生參考文件
• 產生 Kubernetes 組件和工具的參考文件
• 為 kubectl 命令產生參考文件