拉取請求提交和審閱

提交更改

價值觀和參與

我們希望 MDN Web 文件成為一個熱情友好的社群，一個我們都能引以為傲的社群。所有參與者都必須遵守我們的社群參與準則，該準則源自 Mozilla 的社群參與準則。在開啟拉取請求、撰寫評審評論、與拉取請求作者或其他社群成員互動時，請保持禮貌和建設性。如果您或其他人經歷了潛在的非法行為，或讓您感到不安全、不受歡迎或不舒服，我們鼓勵您舉報。

開始之前

在開始 MDN 上的工作之前，請先閱讀以下建議和指南。

拉取請求必須解決或部分修復現有問題。我們設定此限制的原因是為了避免您開始任何其他人可能已經在進行的工作。搜尋您要貢獻的MDN 倉庫中的問題和拉取請求，並確認您要開始的工作尚未被其他人進行。在尋求為 MDN 專案貢獻時，您會遇到以下情況之一：

• 如果您希望為專案貢獻，您可以在任何MDN GitHub 倉庫（例如，mdn/content 問題）的“Issues”下和我們的公共 GitHub 專案面板中找到任務。請確保問題未分配給任何人，並且沒有人已經為該任務開啟拉取請求。標有 good first issue 的問題是一個很好的開始。

• 如果您在 MDN 上發現了問題，您應該首先開啟一個問題。在您開始工作之前，問題需要維護者的回覆，這樣您就知道拉取請求解決的問題是有效的，並且您的拉取請求將被接受。有關問題的更多資訊可以在我們的GitHub 問題的社群頁面上找到。

• 如果您想建議新內容或新功能，請透過“新內容或功能建議”GitHub 問題模板提交提案。

如果您不確定從何開始，請在 Discord 伺服器上聯絡我們尋求反饋。

開啟拉取請求

當您準備好開啟拉取請求時，請遵循以下指南：

• 拉取請求應該簡短且只關注一個問題：如果可能，將相關的更改分組到多個小的拉取請求中。如果拉取請求變得太大，評審者可能會關閉它，並要求您為每個邏輯上屬於一起的更改集提交拉取請求。
• 新增更改的描述：為拉取請求提供儘可能多的上下文和理由。
• 新增您正在關閉的問題連結：在拉取請求描述中，如果它完全解決了問題，則新增“Fixes”，如果它是相關問題，則新增“Relates to”。有關在拉取請求中連結到問題的更多資訊可以在GitHub 文件中找到。
• 如果存在必須首先合併的拉取請求（例如，其他倉庫中的程式碼示例），則新增“depends on”並附上依賴項鍊接。
• 程式碼示例更改應與內容更改同時進行：這對於確保更新的示例正確提供非常重要。如果您正在進行影響示例使用方式的內容更改，則相關的程式碼示例也應該更新。
• 新增評審者：如果您已經知道誰應該評審您的拉取請求，您可以新增評審者，例如團隊成員或主題所有者。
• 不要只進行語法更改：MDN Web Docs 包含技術文件；除非語法不正確，否則您不應建議散文風格的更改。
• 對於遵循特定格式樣式的頁面，不要不必要地新增或刪除換行符。

開啟拉取請求後

• 處理 CI 失敗：來自作為 GitHub Actions 執行的自動化測試（請參閱 .github/workflows）。如果這些測試中的一個或多個失敗，您有責任嘗試解決它們。如果您不知道如何解決潛在問題，請尋求幫助。
• 解決與主分支的合併衝突；您負責解決這些衝突。您可以透過將 mdn/main 分支合併到您的分支來完成此操作。有關更多資訊，請參閱 GitHub 文件中關於保持分支最新的內容。
• 及時響應反饋。這意味著準備根據評審對拉取請求進行更改。如果進行了評審但未進行更改，拉取請求可能會被關閉。
• 在評審過程中保持耐心。MDN 組織會收到大量拉取請求，團隊可能需要時間來評審您的貢獻。
• 不要重新開啟已關閉的拉取請求。如果必須建立新的拉取請求，它可以引用已關閉的拉取請求。

拉取請求評審流程

當您根據 CODEOWNERS 檔案開啟拉取請求時，評審者會自動分配，但如果您有特定的評審人，您可以手動請求評審。我們還對拉取請求使用自動標籤，以幫助我們進行分類。維護者可以根據需要進一步分類拉取請求並新增任何其他標籤，例如 needs-info 或 on-hold。

如果您想評審拉取請求但未被列為評審者，您可以將自己新增為評審者。禮貌的做法是先在拉取請求上評論，表明您打算開始評審，與現有評審者進行確認。

評審者和分配者

MDN Web Docs 團隊使用評審者和分配者來跟蹤拉取請求的狀態。

• 評審者是評估拉取請求中的更改並向作者提供反饋的人。
• 分配者是負責確保拉取請求不被阻塞的人。並非所有拉取請求都有分配者，但如果有，他們負責確保拉取請求順利進行。分配者透過合併、關閉或自己進行解除阻塞的工作來幫助工作達成結論。

拉取請求評審者或分配者負責合併更改。

在開始評審之前，請檢查拉取請求描述，確保沒有人特別需要評審。確保所有持續整合 (CI) 任務都已成功完成，並且沒有合併衝突。

如果任何任務失敗或存在合併衝突，請將其告知作者；解決這些問題是他們的責任。您可以將作者設定為分配者，以指示拉取請求在開始評審之前需要他們的關注。請為作者留出尋求幫助的空間，尤其是對專案的新貢獻者。

評審拉取請求

對於拉取請求中的更改，內容和文字必須符合MDN 寫作風格指南，示例程式碼必須遵循程式碼風格指南。

當您評審拉取請求時，您應該：

• 新增評論：在拉取請求中新增評論，讓作者知道您已注意到該拉取請求並將開始評審。這是為了避免不必要地同時開始評審拉情況。
• 限制評審範圍：僅限於拉取請求中的更改。開啟一個後續問題或拉取請求，以解決拉取請求未涵蓋的其他改進。
• 尋求幫助：如果您在評審過程中需要技術協助，請新增 review-help-needed 標籤。
• 關閉包含不相關更改的拉取請求：如果它過於複雜或包含多個不相關的更改。在這種情況下，請拉取請求作者分批提交他們的更改。
• 請求負載均衡：如果您的工作量已滿且沒有時間進行評審。標記 @core-yari-content 團隊，詢問是否有人可以接替。
• 在“depends on”的拉取請求合併之前，請勿合併。
• 不要合併有失敗測試的拉取請求。保持 main 分支穩定，避免對貢獻者、維護者和自動化流程造成干擾，這是良好的開源禮儀。不穩定的 main 分支會阻塞所有其他拉取請求，並使其他人難以評審和合並貢獻。此外，關注倉庫的貢獻者會收到大量通知，而由失敗測試引起的冗餘通知可能會令人沮喪。如果您不確定如何修復失敗的測試，請尋求幫助或將拉取請求分配給其他人。

如果一個拉取請求除了小的拼寫錯誤或其他小問題外看起來不錯，您可能希望直接修復該問題。只要拉取請求已設定為允許更改，您就可以這樣做。建議使用帶有建議的評論來修復小問題，因為它們可以批次提交。

提交評審時，您有三個選項：批准、評論或請求更改。以下部分解釋了何時使用每個選項。

請求更改

當您提供的反饋*需要*由作者處理並由評審者重新評審後，拉取請求才能被批准和合並時，請使用“請求更改”選項。

Comment

當您的反饋不關鍵且不需要重新評審時，請使用“評論”選項。簡而言之，您相信作者和其他評審者會做出良好的判斷。

批准

當一切看起來都很好並且從您的角度來看已準備好合併時，請使用“批准”選項。提交評審後，如果沒有其他評審者或任何待處理的評審意見需要解決，您可以安全地合併拉取請求。

如果遇到困難該怎麼辦

如果您不理解內容更改或覺得它太大太複雜而無法處理，請不要驚慌！一個好的開始方法是向拉取請求作者詢問資訊以尋求幫助。

您很少會被要求在沒有警告的情況下評審一個大型複雜的更改。但是，如果發生這種情況，拉取請求描述中應該連結到一個解釋背景資訊的問題。

如果您仍然不確定或認為內容可疑，請聯絡 MDN Web Docs 團隊尋求幫助。

作者和評審者的週轉時間指南

本節詳細介紹了作為拉取請求作者響應評審意見的預期週轉時間，以及作為評審者評審拉取請求的預期週轉時間。

• 評審：拉取請求評審者應該能夠在 2 周或更短的時間內評審更改。在拉取請求開啟後的 2 周內，評審者可以：
  • 留下評論，說明他們何時可以開始評審拉取請求。
  • 尋求技術或資源幫助。
• 解決請求的更改：拉取請求作者應該能夠在 4 周或更短的時間內回覆或修復評論。如果拉取請求作者無法在該時間內回覆或修復評審評論，評審者可以執行以下操作之一：
  • 提交更改併合並拉取請求。
  • 關閉拉取請求。

外部評審者

MDN 內容倉庫中的一些拉取請求與瀏覽器供應商或具有明確作者和評審者的組織進行的特定工作相關。在這種情況下，作者將在拉取請求描述底部的行中包含評審者的使用者名稱，例如：

reviewer: @jpmedley

如果您收到評審請求，並且您已被上述方式指定的其他評審者覆蓋，請不要評審更改。一旦描述中提到的評審者批准了更改，他們將請求 CODEOWNERS 所需的批准。

閱讀列表

鼓勵評審者閱讀以下文章以獲取常見任務的幫助：

• The Art of Closing 解釋瞭如何關閉未完成或被拒絕的拉取請求。
• Kindness and Code Reviews: Improving the Way We Give Feedback 提供了有用的反饋提示。
• Code Review Guidelines for the Reviewer 提供了良好和不良反饋的示例。
• How to do a code review on google.github.io/eng-practices。