開啟拉取請求

要貢獻新內容頁面或改進現有內容頁面，請開啟一個 Pull Request (PR)。確保您遵循開始之前部分的所有要求。

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

如果您的更改很大，請閱讀從本地 fork 開始工作以瞭解如何在本地計算機上進行更改。

使用 GitHub 進行的更改

如果您對 Git 工作流不太熟悉，這裡有一個更簡單的方法來開啟 Pull Request。圖 1 概述了這些步驟，詳細資訊如下。

flowchart LR A([fa:fa-user New
Contributor]) --- 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. 在編輯器下方，填寫“建議檔案更改”表單。在第一個欄位中，為您的提交訊息新增標題。在第二個欄位中，提供描述。

  4. 選擇“建議檔案更改”。

  5. 選擇“建立 Pull Request”。

  6. 將出現“開啟 Pull Request”螢幕。填寫表單。

    • Pull Request 的“主題”欄位預設為提交摘要。如果需要，可以更改它。
    • “正文”包含您的擴充套件提交訊息（如果您有的話）以及一些模板文字。將模板文字要求的詳細資訊新增到其中，然後刪除多餘的模板文字。
    • 保留“允許維護者編輯”複選框的選中狀態。

  7. 選擇“建立 Pull Request”。

在 GitHub 中處理反饋

在合併 Pull Request 之前，Kubernetes 社群成員會對其進行審查和批准。k8s-ci-robot 會根據頁面中提到的最近所有者推薦審閱者。如果您有特定的人選，請在評論中留下他們的 GitHub 使用者名稱。

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

  1. 轉到“已更改檔案”選項卡。
  2. 選擇 Pull Request 所更改的任何檔案上的鉛筆（編輯）圖示。
  3. 進行請求的更改。
  4. 提交更改。

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

審查完成後，審閱者會合並您的 PR，您的更改將在幾分鐘後上線。

從本地 fork 開始工作

如果您對 Git 更熟悉，或者您的更改大於幾行，請從本地 fork 開始工作。

確保您的計算機上已安裝 Git。您也可以使用 Git UI 應用程式。

圖 2 展示了從本地 fork 工作時要遵循的步驟。每個步驟的詳細資訊如下。

flowchart LR 1[Fork kubernetes/website
repository] --> 2[建立本地克隆
並設定 upstream] subgraph changes[您的更改] direction TB S[ ] -.- 3[建立分支
例如：my_new_branch] --> 3a[使用
文字編輯器進行更改] --> 4["本地預覽您的更改
使用 Hugo
(localhost:1313)
或構建容器映象"] end subgraph changes2[Commit / Push] 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”。

建立本地克隆並設定 upstream

  1. 在終端視窗中，克隆您的 fork 並更新Docsy Hugo 主題

    git clone git@github.com:<github_username>/website
cd website

  2. 導航到新的 website 目錄。將 kubernetes/website 儲存庫設定為 upstream remote

    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. 將“未暫存的更改”下的檔案新增到提交中

    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. 在本地儲存庫中獲取子模組依賴項

    # Run this in a terminal
make module-init

  3. 在容器中啟動 Hugo

    # Run this in a terminal
make container-serve

  4. 在 Web 瀏覽器中，導航到 https://:1313。Hugo 會監視更改並根據需要重新構建站點。

  5. 要停止本地 Hugo 例項，請返回終端並鍵入 Ctrl+C，或關閉終端視窗。

或者，在您的計算機上安裝並使用 hugo 命令

  1. 安裝Hugo (Extended edition) 和 Node 版本（如 website/netlify.toml 中指定）。

  2. 安裝任何依賴項

    npm ci

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

    cd <path_to_your_repo>/website
make serve

    如果您使用的是 Windows 計算機或無法執行 make 命令，請使用以下命令

    hugo server --buildFuture

  4. 在 Web 瀏覽器中，導航到 https://:1313。Hugo 會監視更改並根據需要重新構建站點。

  5. 要停止本地 Hugo 例項，請返回終端並鍵入 Ctrl+C，或關閉終端視窗。

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

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

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

flowchart LR subgraph first[ ] direction TB 1[1. 轉到 kubernetes/website 儲存庫] --> 2[2. 選擇“新建 Pull Request”] 2 --> 3[3. 選擇“跨 fork 比較”] 3 --> 4[4. 從
head repository 下拉選單中選擇您的 fork] end subgraph second [ ] direction TB 5[5. 從
compare 下拉選單中選擇您的分支] --> 6[6. 選擇“建立 Pull Request”] 6 --> 7[7. 新增描述
到您的 PR] 7 --> 8[8. 選擇“建立 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. 在 Web 瀏覽器中，轉到kubernetes/website 儲存庫。

  2. 選擇“新建 Pull Request”。

  3. 選擇“跨 fork 比較”。

  4. 從“head repository”下拉選單中，選擇您的 fork。

  5. 從“compare”下拉選單中，選擇您的分支。

  6. 選擇“建立 Pull Request”。

  7. 為您的 Pull Request 新增描述

    • 標題（50 個字元以內）：概括更改的意圖。

    • 描述：更詳細地描述更改。

      • 如果存在相關的 GitHub issue，請在描述中包含 Fixes #12345 或 Closes #12345。如果使用，GitHub 的自動化將在合併 PR 後關閉提到的 issue。如果存在其他相關的 PR，也請連結它們。
      • 如果您想就特定事項獲得建議，請在描述中包含您希望審閱者思考的任何問題。

  8. 選擇“建立 Pull Request”按鈕。

恭喜！您的 Pull Request 已在Pull requests 中可用。

開啟 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 獲取提交併 rebase 您的工作分支

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

  2. rebase 後，強制推送到您的 fork

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

合併衝突和 rebase

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

  1. 更新您的 fork 並 rebase 您的本地分支

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

    然後強制將更改推送到您的 fork

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

  2. 從 kubernetes/website 的 upstream/main 獲取更改並 rebase 您的分支

    git fetch upstream
git rebase upstream/main

  3. 檢查 rebase 的結果

    git status

    這將導致許多檔案被標記為已衝突。

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

  5. 將檔案新增到更改集

    git add <filename>

  6. 繼續 rebase

    git rebase --continue

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

    應用所有提交後，git status 命令會顯示 rebase 已完成。

  8. 將分支強制推送到您的 fork

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

    Pull Request 不再顯示任何衝突。

壓縮提交

如果您的 PR 有多個提交，則必須在合併 PR 之前將它們壓縮成一個提交。您可以在 PR 的“Commits”選項卡中檢查提交數量，或在本地執行 git log 命令。

  1. 開始互動式 rebase

    git rebase -i HEAD~<number_of_commits_in_branch>

    壓縮提交是 rebase 的一種形式。-i 開關告訴 Git 您要進行互動式 rebase。HEAD~<number_of_commits_in_branch 表示要檢視多少個提交進行 rebase。

    輸出類似如下：

    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.

    輸出的第一部分列出了 rebase 中的提交。第二部分列出了每個提交的選項。更改 pick 這個詞會改變 rebase 完成後該提交的狀態。

    為了 rebase 的目的，請專注於 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 模板。檢視一些開啟的 issues 和 PRs，以瞭解該團隊的流程。提交 issues 或 PRs 時，請務必儘可能詳細地填寫模板。

下一步

  • 閱讀審查以瞭解有關審查過程的更多資訊。
最後修改日期：2025 年 2 月 4 日下午 6:46 PST：使用正確的步驟安裝 Docsy 主題並與 Hugo 一起使用來更新文件。 (9538fde064)