審閱提取請求

任何人都可以審閱文件提取請求。請造訪 Kubernetes 網站儲存庫中的提取請求區段，以查看開啟的提取請求。

審閱文件提取請求是向 Kubernetes 社群自我介紹的好方法。它可以幫助您學習程式碼庫，並與其他貢獻者建立信任。

在審閱之前，最好先

• 閱讀內容指南和樣式指南，以便您可以留下知情的評論。
• 了解 Kubernetes 文件社群中不同的角色和職責。

在您開始之前

在您開始審閱之前

• 閱讀CNCF 行為準則，並確保您始終遵守它。
• 保持禮貌、體貼和樂於助人。
• 評論 PR 的正面方面以及變更。
• 保持同理心，並注意您的審閱可能如何被接收。
• 假設良好的意圖並提出澄清問題。
• 經驗豐富的貢獻者，請考慮與需要大量變更的新貢獻者配對。

審閱流程

一般而言，審閱提取請求的內容和英文樣式。圖 1 概述了審閱流程的步驟。每個步驟的詳細資訊如下。

圖 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 描述以了解所做的變更，並閱讀任何連結的問題
   • 閱讀其他審閱者的任何評論
   • 按一下 [Files changed] 索引標籤以查看已變更的檔案和行
   • 透過捲動到 [Conversation] 索引標籤底部的 PR 建置檢查區段，預覽 Netlify 預覽建置中的變更。以下是螢幕截圖 (這顯示 GitHub 的桌面網站；如果您在平板電腦或智慧型手機裝置上進行審閱，GitHub Web UI 略有不同)

     

     若要開啟預覽，請按一下檢查清單中 [deploy/netlify] 行的 [Details] 連結。

4. 前往 [Files changed] 索引標籤以開始您的審閱。

   1. 按一下您要評論的行旁邊的 + 符號。
   2. 填寫您對該行的任何評論，然後按一下 [Add single comment] (如果您只有一個評論要發表) 或 [Start a review] (如果您有多個評論要發表)。
   3. 完成後，按一下頁面頂端的 [Review changes]。在這裡，您可以新增審閱摘要 (並為貢獻者留下一些正面評論！)。請務必始終使用「評論」

   • 完成審閱後，請避免點擊「Request changes」（要求變更）按鈕。如果您希望在進一步修改完成前阻止 PR 合併，可以留下 "/hold" 評論。請說明您設定 hold 的原因，並可選擇性地指定您或其他審閱者可以解除 hold 的條件。

   • 完成審閱後，請避免點擊「Approve」（核准）按鈕。在大多數情況下，建議留下 "/approve" 評論。

審閱檢查清單

審閱時，請以下列項目作為起點。

語言與文法

• 語言或文法是否有明顯錯誤？是否有更好的措辭方式？
  • 請專注於作者正在變更的頁面部分的語言和文法。除非作者明確旨在更新整個頁面，否則他們沒有義務修正頁面上的所有問題。
  • 當 PR 更新現有頁面時，您應該專注於審閱正在更新的頁面部分。變更的內容應審閱其技術和編輯上的正確性。如果您在頁面上發現與 PR 作者試圖解決的問題沒有直接關係的錯誤，則應將其視為個別問題（首先檢查是否已存在關於此問題的 issue）。
  • 請留意移動內容的 pull request。如果作者重新命名頁面或合併兩個頁面，我們（Kubernetes SIG Docs）通常會避免要求作者修正移動內容中我們可能發現的所有文法或拼字錯誤。
• 是否有任何複雜或過時的詞語可以用更簡單的詞語替換？
• 是否有任何正在使用的詞語、術語或短語可以用非歧視性的替代方案替換？
• 用字遣詞及其大小寫是否遵循風格指南？
• 是否有可以縮短或簡化的長句？
• 是否有任何長段落可以更好地轉換為列表或表格？

內容

• 在 Kubernetes 網站上其他地方是否存在類似內容？
• 內容是否過度連結到站外、個別供應商或非開放原始碼的文件？

網站

• 此 PR 是否變更或移除了頁面標題、slug/別名或錨點連結？如果是，此 PR 是否導致連結失效？是否有其他選項，例如變更頁面標題但不變更 slug？

• PR 是否引入新頁面？如果是，

  • 頁面是否使用正確的頁面內容類型和相關的 Hugo shortcode？
  • 頁面是否正確顯示在該章節的側邊導覽列中（或完全顯示）？
  • 頁面是否應顯示在文件首頁列表中？

• 變更是否顯示在 Netlify 預覽中？請特別留意列表、程式碼區塊、表格、注意事項和圖片。

部落格

• 歡迎透過 Google 文件或 HackMD 對部落格文章提供早期回饋。請儘早向 #sig-docs-blog Slack 頻道請求意見。

• 在審閱部落格 PR 之前，請先熟悉提交部落格文章和案例研究。

• 我們願意鏡像發布到 https://kubernetes.dev/blog/（貢獻者部落格）的任何部落格文章，前提是

• 鏡像文章的發布日期與原始文章相同（發布時間也應相同，但在特殊情況下，您也可以設定最多晚 12 小時的時間戳記）

  • 對於到達的 PR，原始文章已合併到 https://kubernetes.dev/，在原始文章和鏡像文章 [將] 發布之間，主要部落格沒有發布任何文章。這是因為我們不希望將文章添加到人們的 feed 中，例如 RSS，除非在他們 feed 的最末端。
  • 原始文章沒有違反任何強烈建議的審閱指南或社群規範。
  • 您應該為鏡像文章設定標準網址，指向原始文章的網址（您可以使用預覽來預測網址並提前填寫）。請使用 front matter 中的 canonicalUrl 欄位來執行此操作。

• 請考慮目標受眾，以及部落格文章是否適合 kubernetes.io。例如，如果目標受眾僅為 Kubernetes 貢獻者，則 kubernetes.dev 可能更適合，或者如果部落格文章是關於一般平台工程，則可能更適合在另一個網站上發布。

  此考量也適用於鏡像文章；雖然如果開啟 PR，我們願意考慮所有有效的貢獻者文章進行鏡像，但我們並非鏡像所有文章。

• 只有在 Kubernetes 專案願意承諾無限期維護部落格文章時，我們才會將其標記為已維護（在 front matter 中設定 evergreen: true）。有些部落格文章絕對值得這樣做，我們總是將我們的發布公告標記為 evergreen。如果您不確定如何審閱此點，請諮詢其他貢獻者。

• 內容指南無條件適用於部落格文章和新增它們的 PR。請記住，指南中的某些限制聲明它們僅與文件相關；這些限制不適用於部落格文章。

• 風格指南大致也適用於部落格 PR，但我們做了一些例外。

  • 在有多位作者的部落格文章中，或文章引言清楚表明作者代表特定群體撰寫文章時，可以使用「we」是可以接受的。
  • 我們避免在標註（例如 {{< caution >}}）中使用 Kubernetes shortcode
  • 關於未來的陳述是可以接受的，儘管我們代表 Kubernetes 在官方公告中謹慎使用它們
  • 程式碼範例不需要使用 {{< code_sample >}} shortcode，而且通常不使用會更好
  • 我們允許作者以他們自己的寫作風格撰寫文章，只要大多數讀者都能理解要點即可

• 圖表指南的目標是 Kubernetes 文件，而不是部落格文章。與其保持一致仍然很好，但是

  • 我們偏好 SVG 而非點陣圖圖表格式，也優於 Mermaid（您仍然可以在註解中擷取 Mermaid 原始碼）
  • 無需將圖表標題設為圖 1、圖 2 等

其他

• 請留意瑣碎的編輯；如果您看到您認為是瑣碎編輯的變更，請指出該政策（如果變更確實是改進，仍然可以接受）。
• 鼓勵進行空白字元修正的作者在其 PR 的第一個 commit 中執行此操作，然後在其之上新增其他變更。這使得合併和審閱都更容易。特別留意在單一 commit 中發生的瑣碎變更，以及大量的空白字元清理（如果您看到這種情況，請鼓勵作者修正）。

作為審閱者，如果您發現 PR 中存在不影響含義的小問題，例如錯字或不正確的空白字元，請在您的評論前加上 nit: 前綴。這讓作者知道您的回饋的這部分並不重要。

如果您正在考慮核准 pull request，並且所有剩餘的回饋都標記為 nit，您可以直接合併 PR。在這種情況下，針對剩餘的 nit 開啟 issue 通常很有用。請考慮您是否能夠滿足將新 issue 標記為適合新手入門的 issue 的要求；如果可以，這些是很好的來源。