審查拉取請求

任何人都可以審查文件的拉取請求。請訪問 Kubernetes 網站倉庫中的 拉取請求 部分，檢視開放的拉取請求。

審查文件拉取請求是向 Kubernetes 社群介紹自己的絕佳方式。它能幫助你瞭解程式碼庫並與其他貢獻者建立信任。

在審查之前，最好先

準備工作

開始審查之前

  • 請閱讀 CNCF 行為準則，並確保你始終遵守它。
  • 保持禮貌、體貼和樂於助人。
  • 評論 PR 的積極方面以及修改之處。
  • 要富有同情心，並注意你的審查可能會如何被接收。
  • 假定對方是善意的，並提出澄清性問題。
  • 有經驗的貢獻者，請考慮與那些需要大量修改的初級貢獻者進行配對。

審查流程

通常，請以英文審查內容和樣式的拉取請求。圖 1 概述了審查流程的步驟。每個步驟的詳細資訊如下。

flowchart LR subgraph fourth[開始審查] direction TB S[ ] -.- M[新增評論] --> N[審查更改] N --> O[初級貢獻者應
選擇“評論”]
end subgraph third[選擇 PR] direction TB T[ ] -.- J[閱讀描述
和評論]--> K[在 Netlify 預覽構建中預覽更改]
end A[檢視開放的 PR 列表]--> B[按標籤篩選開放的 PR] B --> third --> fourth 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 spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,B,J,K,M,N,O grey class S,T spacewhite class third,fourth white

圖 1. 審查流程步驟。

  1. 前往 https://github.com/kubernetes/website/pulls。你將看到針對 Kubernetes 網站和文件的所有開放拉取請求的列表。

  2. 使用以下一個或多個標籤來篩選開放的 PR：

    • cncf-cla: yes (推薦)：尚未簽署 CLA 的貢獻者提交的 PR 無法合併。有關更多資訊，請參閱 簽署 CLA。
    • language/en (推薦)：僅篩選英文 PR。
    • size/<size>：按特定大小篩選 PR。如果你是新手，請從較小的 PR 開始。

    此外，請確保 PR 未被標記為“進行中”。使用 work in progress 標籤的 PR 尚未準備好進行審查。

  3. 一旦你選擇了一個 PR 進行審查，請透過以下方式瞭解更改：

    • 閱讀 PR 描述以瞭解所做的更改，並閱讀任何連結的問題
    • 閱讀其他審查者的任何評論
    • 點選“已更改檔案”選項卡以檢視更改的檔案和行
    • 透過滾動到“對話”選項卡底部的 PR 構建檢查部分，在 Netlify 預覽構建中預覽更改。這是截圖（顯示的是 GitHub 的桌面網站；如果你在平板電腦或智慧手機上審查，GitHub 網頁介面會略有不同）
      GitHub pull request details including link to Netlify preview
      要開啟預覽，請點選檢查列表中 deploy/netlify 行的“詳細資訊”連結。

  4. 前往“已更改檔案”選項卡開始你的審查。

    1. 點選要評論的行旁邊的 + 符號。
    2. 填寫你對該行的任何評論，然後點選“新增單個評論”（如果你只有一個評論要發表）或“開始審查”（如果你有多個評論要發表）。
    3. 完成後，點選頁面頂部的“審查更改”。在這裡，你可以新增你的審查摘要（併為貢獻者留下一些積極的評論！）。請始終使用“評論”

    • 完成審查時，請避免點選“請求更改”按鈕。如果你想阻止 PR 在進一步更改完成之前被合併，可以留下“/hold”評論。說明設定 hold 的原因，並可選擇指定你或其他審查者可以解除 hold 的條件。

    • 完成審查時，請避免點選“批准”按鈕。大多數情況下，建議留下“/approve”評論。

審查清單

審查時，請參考以下內容作為起點。

語言和語法

  • 語言或語法上是否存在明顯的錯誤？是否有更好的措辭方式？
    • 關注作者正在更改的頁面部分的語言和語法。除非作者明確打算更新整個頁面，否則他們沒有義務修復頁面上的所有問題。
    • 當 PR 更新現有頁面時，你應該專注於審查 PR 作者試圖解決的部分。這些更改的內容應在技術和編輯上進行準確性審查。如果你在頁面上發現與 PR 作者試圖解決的問題不直接相關的問題，那麼應該將其視為一個單獨的問題（首先檢查是否已存在關於此的 issue）。
    • 留意移動內容的拉取請求。如果作者重新命名頁面或合併兩個頁面，我們（Kubernetes SIG Docs）通常會避免要求該作者修復我們在移動內容中發現的每個語法或拼寫錯誤。
  • 是否存在可以用更簡單的詞語替換的複雜或古老的詞語？
  • 是否存在可以使用非歧視性替代詞語、術語或短語？
  • 用詞和大小寫是否遵循 樣式指南？
  • 是否存在可以縮短或簡化結構的冗長句子？
  • 是否存在冗長的段落，如果改為列表或表格會更好？

內容

  • Kubernetes 網站上是否存在類似的內容？
  • 內容是否過多地連結到站外、個別供應商或非開源文件？

文件

一些需要考慮的檢查

  • 此 PR 是否更改或刪除了頁面標題、slug/別名或錨點連結？如果是，是否因此 PR 導致了死鏈？是否有其他選擇，例如在不更改 slug 的情況下更改頁面標題？

  • PR 是否引入了一個新頁面？如果是

    • 頁面是否使用了正確的 頁面內容型別 和相關的 Hugo 短程式碼？
    • 頁面是否在章節的側邊導航中（或是否出現）正確顯示？
    • 頁面是否應顯示在 Docs Home 列表中？

  • Netlify 預覽中是否顯示了更改？請特別注意列表、程式碼塊、表格、註釋和影像。

部落格

透過 Google Doc 或 HackMD 即可對部落格文章提供早期反饋。請儘早向 #sig-docs-blog Slack 頻道請求輸入。

在審查部落格 PR 之前，請熟悉 部落格指南 以及 提交部落格文章和案例研究。

請確保你也瞭解 長期維護的文章以及如何判斷一篇文章是否是長期維護的。

部落格文章可能包含 直接引用和 間接引用。即使你認為原始說話者的語法不正確，也要避免建議修改被歸因於某人或已發生的對話的內容。對於這些情況，也請儘量尊重文章作者建議的標點符號，除非它明顯錯誤。

作為一個專案，我們僅將部落格文章標記為長期維護（在 front matter 中設定為 evergreen: true），如果 Kubernetes 專案願意承諾無限期地維護它們。一些部落格文章絕對值得這樣做，我們始終將釋出公告標記為長期維護。如果你不確定如何在此方面進行審查，請與其他貢獻者核實。

《內容指南》無條件適用於部落格文章及其新增它們的 PR。請注意，指南中的某些限制宣告僅與文件相關；這些限制不適用於部落格文章。

檢查 Markdown 源是否使用了正確的 頁面內容型別 和/或 layout。

其他

留意 微小編輯；如果你看到你認為屬於微小編輯的更改，請指出該政策（如果它確實是一個改進，接受該更改仍然是可以的）。

鼓勵進行空白字元修復的作者在 PR 的第一個 commit 中進行，然後在上面新增其他更改。這使得合併和審查都更容易。特別留意發生在單個 commit 中，並伴有大量空白字元清理的微小更改（如果你看到這種情況，請鼓勵作者進行修復）。

作為審查者，如果你識別出 PR 的小問題，而這些問題並不影響核心意義，例如拼寫錯誤或不正確的空格，請在評論前加上 nit:。這會讓作者知道你反饋的這部分是非關鍵的。

如果你正在考慮批准一個 PR，並且所有剩餘的反饋都被標記為 nit，那麼你仍然可以合併該 PR。在這種情況下，通常可以就剩餘的 nit 開啟一個 issue。考慮你是否能夠滿足將新 issue 標記為 Good First Issue 的要求；如果你可以，這些是一個很好的來源。

最後修改時間：2025 年 3 月 13 日上午 10:41 PST：新增部落格貢獻指南（815a75d025）