開啟 Pull Request

若要貢獻新的內容頁面或改進現有的內容頁面，請開啟 Pull Request (PR)。請確定您遵循開始之前章節中的所有需求。

如果您的變更很小，或者您不熟悉 git，請閱讀使用 GitHub 進行變更以瞭解如何編輯頁面。

如果您的變更很大，請閱讀從本機分支工作以瞭解如何在您電腦的本機上進行變更。

使用 GitHub 進行變更

如果您對 git 工作流程不太熟悉，以下是開啟 Pull Request 的更簡易方法。圖 1 概述了步驟，詳細資訊如下。

flowchart LR A([fa:fa-user 新的
貢獻者]) --- id1[(kubernetes/website
GitHub)] subgraph tasks[使用 GitHub 進行變更] direction TB 0[ ] -.- 1[1. 編輯此頁面] --> 2[2. 使用 GitHub markdown
編輯器進行變更] 2 --> 3[3. 填寫建議檔案變更] end subgraph tasks2[ ] direction TB 4[4. 選擇建議檔案變更] --> 5[5. 選擇建立 Pull Request] --> 6[6. 填寫開啟 Pull Request] 6 --> 7[7. 選擇建立 Pull Request] end id1 --> tasks --> tasks2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,1,2,3,4,5,6,7 grey class 0 spacewhite class tasks,tasks2 white class id1 k8s

圖 1. 使用 GitHub 開啟 PR 的步驟。

  1. 在您看到問題的頁面上，選取右手邊導覽面板中的編輯此頁面選項。

  2. 在 GitHub markdown 編輯器中進行變更。

  3. 在編輯器下方，填寫Propose file change（提議檔案變更）表單。在第一個欄位中，為您的提交訊息加上標題。在第二個欄位中，提供描述。

  4. 選取Propose file change（提議檔案變更）。

  5. 選取Create pull request（建立 Pull Request）。

  6. 畫面上會出現Open a pull request（開啟 Pull Request）畫面。填寫表單

    • Pull Request 的Subject（主旨）欄位預設為提交摘要。您可以視需要變更。
    • Body（內文）包含您擴充的提交訊息（若有的話）和一些範本文字。加入範本文字要求的詳細資訊，然後刪除額外的範本文字。
    • 保持選取Allow edits from maintainers（允許維護者編輯）核取方塊。

  7. 選取Create pull request（建立 Pull Request）。

在 GitHub 中處理回饋

在合併 Pull Request 之前，Kubernetes 社群成員會審閱並批准它。k8s-ci-robot 會根據頁面中提及的最接近的擁有者來建議審閱者。如果您有特定人選，請在評論中留下他們的 GitHub 使用者名稱。

如果審閱者要求您進行變更

  1. 前往 Files changed（檔案變更）標籤頁。
  2. 在 Pull Request 變更的任何檔案上，選取鉛筆（編輯）圖示。
  3. 進行要求的變更。
  4. 提交變更。

如果您正在等待審閱者，請每 7 天聯繫一次。您也可以在 #sig-docs Slack 頻道中發訊息。

當您的審閱完成時，審閱者會合併您的 PR，您的變更會在幾分鐘後生效。

從本機 Fork 工作

如果您對 git 比較有經驗，或者您的變更大於幾行，請從本機 Fork 工作。

請確保您的電腦上已安裝 git。您也可以使用 git UI 應用程式。

圖 2 顯示從本機 Fork 工作時要遵循的步驟。每個步驟的詳細資訊如下。

flowchart LR 1[Fork kubernetes/website
儲存庫] --> 2[建立本機副本
並設定上游] subgraph changes[您的變更] direction TB S[ ] -.- 3[建立分支
範例：my_new_branch] --> 3a[使用以下工具進行變更
文字編輯器] --> 4["在本機預覽您的變更
使用 Hugo
(localhost:1313)
或建立容器映像檔"] end subgraph changes2[提交 / 推送] direction TB T[ ] -.- 5[提交您的變更] --> 6[推送提交至
origin/my_new_branch] end 2 --> changes --> changes2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class 1,2,3,3a,4,5,6 grey class S,T spacewhite class changes,changes2 white

圖 2. 從本機 Fork 工作以進行變更。

Fork kubernetes/website 儲存庫

  1. 導覽至 kubernetes/website 儲存庫。
  2. 選取Fork（Fork）。

建立本機副本並設定上游

  1. 在終端機視窗中，複製您的 Fork 並更新 Docsy Hugo 主題

    git clone git@github.com:<github_username>/website
cd website
git submodule update --init --recursive --depth 1

  2. 導覽至新的 website 目錄。將 kubernetes/website 儲存庫設定為 upstream 遠端

    cd website

git remote add upstream https://github.com/kubernetes/website.git

  3. 確認您的 origin 和 upstream 儲存庫

    git remote -v

    輸出類似於

    origin	git@github.com:<github_username>/website.git (fetch)
origin	git@github.com:<github_username>/website.git (push)
upstream	https://github.com/kubernetes/website.git (fetch)
upstream	https://github.com/kubernetes/website.git (push)

  4. 從您的 Fork 的 origin/main 和 kubernetes/website 的 upstream/main 提取提交

    git fetch origin
git fetch upstream

    這確保您的本機儲存庫在您開始進行變更之前是最新的。

建立分支

  1. 決定要以哪個分支為基礎進行工作

    • 為了改進現有內容，請使用 upstream/main。
    • 為了新增關於現有功能的內容，請使用 upstream/main。
    • 為了在地化內容，請使用在地化的慣例。如需更多資訊，請參閱在地化 Kubernetes 文件。
    • 為了即將發布的 Kubernetes 版本中的新功能，請使用功能分支。如需更多資訊，請參閱為發布版本編寫文件。
    • 對於多個 SIG Docs 貢獻者協作的長期工作，例如內容重組，請使用為該工作建立的特定功能分支。

    如果您需要分支選擇方面的協助，請在 #sig-docs Slack 頻道中詢問。

  2. 根據步驟 1 中識別的分支建立新分支。此範例假設基礎分支為 upstream/main

    git checkout -b <my_new_branch> upstream/main

  3. 使用文字編輯器進行變更。

隨時使用 git status 命令來查看您已變更哪些檔案。

提交您的變更

當您準備好提交 Pull Request 時，請提交您的變更。

  1. 在您的本機儲存庫中，檢查您需要提交哪些檔案

    git status

    輸出類似於

    On branch <my_new_branch>
Your branch is up to date with 'origin/<my_new_branch>'.

Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified:   content/en/docs/contribute/new-content/contributing-content.md

no changes added to commit (use "git add" and/or "git commit -a")

  2. 將Changes not staged for commit（未暫存以進行提交的變更）下列出的檔案新增至提交

    git add <your_file_name>

    針對每個檔案重複此操作。

  3. 在新增所有檔案後，建立提交

    git commit -m "Your commit message"

  4. 將您的本機分支及其新提交推送至您的遠端 Fork

    git push origin <my_new_branch>

在本機預覽您的變更

最好在推送變更或開啟 Pull Request 之前在本機預覽您的變更。預覽可讓您發現建置錯誤或 Markdown 格式問題。

您可以建置網站的容器映像檔或在本機執行 Hugo。建置容器映像檔速度較慢，但會顯示 Hugo Shortcodes，這對於偵錯可能很有用。

  1. 在本機建置容器映像檔
    只有在您測試 Hugo 工具本身的變更時才需要此步驟

    # Run this in a terminal (if required)
make container-image

  2. 在容器中啟動 Hugo

    # Run this in a terminal
make container-serve

  3. 在網頁瀏覽器中，導覽至 https://127.0.0.1:1313。Hugo 會監看變更並在需要時重建網站。

  4. 若要停止本機 Hugo 執行個體，請返回終端機並輸入 Ctrl+C，或關閉終端機視窗。

或者，在您的電腦上安裝並使用 hugo 命令

  1. 安裝 Hugo 版本，該版本在 website/netlify.toml 中指定。

  2. 如果您尚未更新您的網站儲存庫，則 website/themes/docsy 目錄是空的。網站無法在沒有主題的本機副本的情況下建置。若要更新網站主題，請執行

    git submodule update --init --recursive --depth 1

  3. 在終端機中，前往您的 Kubernetes 網站儲存庫並啟動 Hugo 伺服器

    cd <path_to_your_repo>/website
hugo server --buildFuture

  4. 在網頁瀏覽器中，導覽至 https://127.0.0.1:1313。Hugo 會監看變更並在需要時重建網站。

  5. 若要停止本機 Hugo 執行個體，請返回終端機並輸入 Ctrl+C，或關閉終端機視窗。

從您的 Fork 開啟到 kubernetes/website 的 Pull Request

圖 3 顯示從您的 Fork 開啟到 kubernetes/website 的 PR 的步驟。詳細資訊如下。

請注意，貢獻者可以將 kubernetes/website 提及為 k/website。

flowchart LR subgraph first[ ] direction TB 1[1. 前往 kubernetes/website 儲存庫] --> 2[2. 選取 New Pull Request（新 Pull Request）] 2 --> 3[3. 選取 compare across forks（跨 Fork 比較）] 3 --> 4[4. 從
head repository（head 儲存庫）下拉式選單中選取您的 Fork] end subgraph second [ ] direction TB 5[5. 從
compare（比較）下拉式選單中選取您的分支] --> 6[6. 選取 Create Pull Request（建立 Pull Request）] 6 --> 7[7. 新增描述
到您的 PR] 7 --> 8[8. 選取 Create pull request（建立 Pull Request）] end first --> second classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold class 1,2,3,4,5,6,7,8 grey class first,second white

圖 3. 從您的 Fork 開啟到 kubernetes/website 的 PR 的步驟。

  1. 在網頁瀏覽器中，前往 kubernetes/website 儲存庫。

  2. 選取New Pull Request（新 Pull Request）。

  3. 選取compare across forks（跨 Fork 比較）。

  4. 從 head repository（head 儲存庫）下拉式選單中，選取您的 Fork。

  5. 從 compare（比較）下拉式選單中，選取您的分支。

  6. 選取Create Pull Request（建立 Pull Request）。

  7. 為您的 Pull Request 新增描述

    • Title（標題）（50 個字元或更少）：摘要變更的意圖。

    • Description（描述）：更詳細地描述變更。

      • 如果有相關的 GitHub Issue，請在描述中包含 Fixes #12345 或 Closes #12345。如果使用這些關鍵字，GitHub 的自動化功能會在合併 PR 後關閉提及的 Issue。如果有其他相關的 PR，也請連結這些 PR。
      • 如果您想針對特定事項尋求建議，請在您的描述中包含您希望審閱者思考的任何問題。

  8. 選取 Create pull request（建立 Pull Request）按鈕。

恭喜！您的 Pull Request 已在 Pull requests（Pull Request）中提供。

在開啟 PR 後，GitHub 會執行自動化測試，並嘗試使用 Netlify 部署預覽。

  • 如果 Netlify 建置失敗，請選取 Details（詳細資訊）以取得更多資訊。
  • 如果 Netlify 建置成功，選取 Details（詳細資訊）會開啟 Kubernetes 網站的暫存版本，並套用您的變更。這就是審閱者檢查您的變更的方式。

GitHub 也會自動將標籤指派給 PR，以協助審閱者。如果需要，您也可以新增標籤。如需更多資訊，請參閱新增和移除 Issue 標籤。

在本機處理回饋

  1. 在進行變更後，修改您先前的提交

    git commit -a --amend
    • -a：提交所有變更
    • --amend：修改先前的提交，而不是建立新的提交

  2. 視需要更新您的提交訊息。

  3. 使用 git push origin <my_new_branch> 推送您的變更並重新執行 Netlify 測試。

來自審閱者的變更

有時審閱者會提交到您的 Pull Request。在進行任何其他變更之前，請提取這些提交。

  1. 從您的遠端 Fork 提取提交並重新定基您的工作分支

    git fetch origin
git rebase origin/<your-branch-name>

  2. 在重新定基之後，強制推送新變更到您的 Fork

    git push --force-with-lease origin <your-branch-name>

合併衝突和重新定基

如果另一位貢獻者在另一個 PR 中提交對同一個檔案的變更，則可能會產生合併衝突。您必須解決 PR 中的所有合併衝突。

  1. 更新您的 Fork 並重新定基您的本機分支

    git fetch origin
git rebase origin/<your-branch-name>

    然後強制推送變更到您的 Fork

    git push --force-with-lease origin <your-branch-name>

  2. 從 kubernetes/website 的 upstream/main 提取變更並重新定基您的分支

    git fetch upstream
git rebase upstream/main

  3. 檢查重新定基的結果

    git status

    這會導致許多檔案標記為衝突。

  4. 開啟每個衝突的檔案，並尋找衝突標記：>>>、<<< 和 ===。解決衝突並刪除衝突標記。

  5. 將檔案新增至變更集

    git add <filename>

  6. 繼續重新定基

    git rebase --continue

  7. 視需要重複步驟 2 到 5。

    在套用所有提交後，git status 命令會顯示重新定基已完成。

  8. 強制推送分支到您的 Fork

    git push --force-with-lease origin <your-branch-name>

    Pull Request 不再顯示任何衝突。

壓縮提交

如果您的 PR 有多個提交，您必須在合併 PR 之前將它們壓縮成單個提交。您可以檢查 PR 的 Commits（提交）標籤頁上的提交次數，或在本機執行 git log 命令。

  1. 啟動互動式重新定基

    git rebase -i HEAD~<number_of_commits_in_branch>

    壓縮提交是一種重新定基的形式。-i 參數告訴 git 您想要以互動方式重新定基。HEAD~<number_of_commits_in_branch 指示要查看多少個提交以進行重新定基。

    輸出類似於

    pick d875112ca Original commit
pick 4fa167b80 Address feedback 1
pick 7d54e15ee Address feedback 2

# Rebase 3d18sf680..7d54e15ee onto 3d183f680 (3 commands)

...

# These lines can be re-ordered; they are executed from top to bottom.

    輸出的第一節列出重新定基中的提交。第二節列出每個提交的選項。變更單字 pick 會在重新定基完成後變更提交的狀態。

    為了重新定基的目的，請專注於 squash 和 pick。

  2. 開始編輯檔案。

    變更原始文字

    pick d875112ca Original commit
pick 4fa167b80 Address feedback 1
pick 7d54e15ee Address feedback 2

    改為

    pick d875112ca Original commit
squash 4fa167b80 Address feedback 1
squash 7d54e15ee Address feedback 2

    這會將提交 4fa167b80 Address feedback 1 和 7d54e15ee Address feedback 2 壓縮到 d875112ca Original commit 中，僅留下 d875112ca Original commit 作為時間軸的一部分。

  3. 儲存並退出您的檔案。

  4. 推送您壓縮的提交

    git push --force-with-lease origin <branch_name>

貢獻到其他儲存庫

Kubernetes 專案包含 50 多個儲存庫。其中許多儲存庫包含文件：面向使用者的說明文字、錯誤訊息、API 參考或程式碼註解。

如果您看到想要改進的文字，請使用 GitHub 搜尋 Kubernetes 組織中的所有儲存庫。這可以協助您找出要在哪裡提交您的 Issue 或 PR。

每個儲存庫都有自己的流程和程序。在您提交 Issue 或 PR 之前，請閱讀該儲存庫的 README.md、CONTRIBUTING.md 和 code-of-conduct.md（如果它們存在）。

大多數儲存庫都使用 Issue 和 PR 範本。瀏覽一些開啟的 Issue 和 PR，以了解該團隊的流程。在您提交 Issue 或 PR 時，請務必盡可能詳細地填寫範本。

下一步是什麼？

  • 閱讀審閱以深入瞭解審閱流程。
上次修改時間：2024 年 10 月 16 日下午 4:46 PST：修正本機預覽的錯誤 URL 方案 (cd4f41145f)