Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Pull Request 工作流程

備註

此頁面旨在深入了解我們渴望的拉取請求 (PR) 審核流程。因此，它主要針對負責審查和批准拉取請求的引擎維護人員。話雖如此，大部分內容對於想要了解如何確保其 PR 被合併的潛在貢獻者來說都是有用的。

從高層次來看，拉取請求的理想生命週期如下所示：

  1. 貢獻者開啟修復特定問題的 PR（最好關閉 GitHub issue 或實作 proposal <https://github.com/godotengine/godot-建議> _)。

  2. 其他貢獻者提供有關 PR 的回饋（包括酌情審查和/或批准 PR）。

  3. 引擎維護人員審查程式碼並根據需要提供回饋、請求變更或批准拉取請求。

  4. 另一位維護人員審查程式碼，重點關注程式碼風格/清晰度，並在滿意後批准它。

  5. 如果團隊領導者或「生產團隊<https://godotengine.org/teams#product>」的成員認為拉取請求已充分審查，則可以合併拉取請求。

本文件將更詳細地解釋步驟 2、3、4 和 5。有關拉取請求工作流程的更詳細說明，請參閱拉取請求工作流程檔案 <doc_pr_workflow>`。

備註

在實踐中，這些步驟可以混合在一起。通常，維護人員會同時提供有關程式碼風格和程式碼品質的評論，並批准對兩者的拉取請求。

通常，拉取請求的第一次互動將是引擎維護人員為拉取請求分配標籤，並將其標記為供熟悉該程式碼區域的人員審查。

和/或在 Godot 網站上的「團隊頁面 <https://godotengine.org/teams>」上列出的人員。維護人員負責發動機的特定區域。通常，這意味著他們被給予更多信任來批准和推薦合併拉取請求。

即使您不是維護者，您仍然可以透過檢查程式碼、提供 PR 回饋以及在您的電腦上本地測試 PR 來確認它們是否按預期工作來提供協助。許多目前活躍的維護者在成為維護者之前就開始這樣做了。

程式碼評審與測試

以下是貢獻者和引擎維護者可以對拉取請求進行實質程式碼審查的一系列操作。

備註

如果您想要進行程式碼審查，但無法執行此列表中的所有操作，請在您的審查評論中註明。例如，即使您無法在本機上建立拉取請求來測試拉取請求（反之亦然），提供程式碼註解仍然非常有幫助。請隨意審查程式碼，只需記住在審查結束時記下您僅審查了程式碼，尚未在本地測試更改。

1、確認存在問題

PR 需要解決問題，問題需要記錄下來。確保拉取請求連結並關閉（或至少解決）錯誤或提案。如果沒有，請考慮要求貢獻者更新 PR 的開頭訊息，以更詳細地解釋 PR 旨在解決的問題。

備註

在合併之前應該要清楚_為什麼_需要拉取請求。這有助於審閱者確定 PR 是否按照其所說的那樣進行操作，並幫助將來的貢獻者理解為什麼程式碼是這樣的。

2、測試 PR 並搜尋 Regression

雖然嚴格的程式碼審查和 CI 有助於確保所有拉取請求按預期工作，但錯誤還是會發生，有時貢獻者推送的程式碼除了解決問題之外還會產生問題。維護者將避免合併包含回歸的程式碼，即使它按預期解決了問題。

在審查拉取請求時，請確保 PR 按照其規定執行（即修復連結的錯誤或實作新功能），並且 PR 目標區域以外的任何內容都不會因更改而受到破壞。您可以透過執行編輯器並嘗試編輯器的一些常見功能（為場景新增物件、執行 GDScript、開啟和關閉功能表等）來完成此操作。此外，在檢查程式碼時，請尋找引擎其他部分中的可疑變更。有時，在變基過程中，貢獻者沒有意識到更改會被忽略。

3、進行程式碼評審

程式碼審查通常由在特定領域已經有經驗的人來完成。他們也許能夠提供一些想法，讓程式碼更快、更有條理、或更慣用。但是，即使您經驗不足，您也可能希望進行程式碼審查，以在您願意審查的範圍內提供回饋。這樣做對於區域維護人員來說很有價值（因為對問題的第二雙眼睛總是有幫助的），而且對您也有幫助，因為它將幫助您更熟悉該區域的程式碼，並使您了解其他人是如何做的解決問題。事實上，查看經驗豐富的引擎維護人員的程式碼是了解程式碼庫的好方法。

評審程式碼時，可以對這些內容進行檢查：

  • 程式碼僅涉及 PR（和提交資訊）中提及的領域。

    正如您所看到的，修復程式碼中的隨機內容可能很誘人。然而，這很快就會使拉取請求難以審查，並且難以深入挖掘提交歷史記錄。相關區域旁邊的小修改是可以的，但通常您可以在自己的 PR 中找到的錯誤得到更好的修復。

  • 程式碼正確使用了 Godot 自己的 API 和模式。

    一致性非常重要，程式碼庫中已經存在的解決方案比臨時解決方案更可取。

  • 修改影響核心區域嗎？

    有時，旨在解決當地問題的公關可能會產生超出其範圍的深遠影響。通常最好將程式碼變更保留在出現問題的本地位置。如果您認為解決方案需要在問題範圍之外進行更改，通常最好尋求團隊領導的意見，他可能對如何解決問題有其他想法。

4、與貢獻者反覆運算改進 PR

如果維護人員發現程式碼中需要更改的內容，他們應該提供回饋和改進建議。最好，建議應該按重要性順序排列：首先，解決整體程式碼設計和解決問題的方法，然後確保程式碼符合引擎的最佳實踐，最後，進行程式碼風格審查< doc_code_style_review>`。

備註

在審查過程中儘早溝通合併的障礙。

如果 PR 有明顯的阻礙，或者可能由於任何其他原因而不會被合併，那麼應該儘早、清楚地傳達這一事實。我們希望避免欺騙別人，因為說「對不起，不」感覺很不好。

當您審查拉取請求時，請牢記 Godot 行為準則。特別是以下內容：

  • 任何時候都應該保持禮貌。保持友善和禮貌。

  • 始終假設他人有正面的意圖。

  • 我們隨時歡迎提供回饋，但請保持您的批評具有建設性。

與貢獻者反覆運算拉取請求時，請避免以下情況：

  • 不必要的多次評審。

    換句話說，立即審查完整的 PR，避免無休止地回來指出您在第一次審查中可能注意到的問題。當然，這並不總是可以避免的，但我們應該嘗試一次抓住一切。

  • 過於吹毛求疵。

    程式碼品質可以很靈活，這取決於您所使用的引擎區域。一般來說，我們的程式碼品質標準在核心區域和效能敏感區域比在編輯器程式碼中要高得多。

  • 擴大拉取請求的範圍。

    提供本文或相關/類似的問題或可以類似解決的建議可能會有所幫助，但新增“也可以解決那裡的問題”或“我們也可以新增到此嗎？”對貢獻者並不總是公平的。在決定其他修復是否在範圍內時，請使用您的判斷，但請嘗試使範圍盡可能接近原始拉取請求。

最後，不要因為獨自處理公關而感到壓力。請隨時透過適當的管道或 #general在「Godot 貢獻者聊天 <https://chat.godotengine.org>」_ 上尋求協助。其他團隊可能已經被標記為需要審核，因此您也可以等待或要求他們的協助。

開啟 PR

檢查程式碼後，如果您認為程式碼已準備好合併到引擎中，那麼請繼續並「批准」它。確保也會評論並指定您的審查的性質（即說明您是否在本地運作程式碼，您是否審查了風格和正確性等）。即使您不是引擎維護者，批准拉取請求也會向其他人發出訊號，表明程式碼很好，並且可能解決 PR 所說的問題。作為非引擎維護者批准拉取請求並不能保證程式碼會被合併，其他人仍然會審查它，所以不要害羞。

程式碼樣式方針

一般來說，我們的目標是在風格/清晰度審查之前進行程式碼審查，因為貢獻者通常想知道他們的一般方法是否可以接受，然後再對風格進行挑剔的更改。換句話說，維護者不應該要求貢獻者更改可能需要在後續審查中重寫的程式碼風格。同樣，如果 PR 未經審查，維護者應避免要求貢獻者重新調整 PR。

話雖如此，並不是每個人都有足夠的信心來對程式碼的正確性進行審查，在這種情況下，在進行更實質性的程式碼審查之前提供對程式碼風格和清晰度的評論是完全合適的，並且非常受歡迎。

在實踐中，程式碼風格審查可以作為實質程式碼審查的一部分來完成。重要的是，在合併拉取請求之前，需要審查和考慮實質程式碼和程式碼風格。

在審查程式碼風格時，請特別注意確保拉取請求遵循 doc_code_style_guidelines`。雖然「clang-format」和各種 CI 檢查可以發現很多不一致之處，但它們遠非完美，無法偵測到某些問題。例如，您應該檢查：

  • 標題包含的樣式受到尊重。

  • 標識符使用“snake_case”並遵循我們的命名約定。

  • 方法參數以``p_*`` 或``r_*`` 開頭（如果它們用於傳回值）。

  • 即使是單行條件敘述，也可以適當地使用大括號。

  • 程式碼間隔適當（方法之間只有一個空行，方法體內沒有不必要的空行）。

備註

此列表並不完整，也無意完整。有關完整的規則集，請參閱連結的樣式指南檔案。請記住，「clang-format」可能無法捕捉您希望捕獲的內容，因此請注意並嘗試了解它到底可以偵測到什麼，不能偵測到什麼。

開啟 PR

一般來說，拉取請求只能由生產團隊成員或團隊負責人在其引擎區域內合併拉取請求。例如，網路團隊負責人可以合併網路拉取請求，該請求不會實質更改程式碼的非網路部分。

在實踐中，最好等待生產團隊的成員合併拉取請求，因為他們密切關注整個程式碼庫，並且可能會更好地了解此拉取請求可能與哪些其他最近/即將發生的變更發生衝突（或延遲拉取請求可能有意義的任何其他原因）。請隨意發表評論說 PR 應該準備好合併。

以下是合併拉取請求之前要執行的步驟。對於簡單/直接的拉取請求，您遵守這些步驟的程度可以很靈活，但對於複雜或有風險的拉取請求，應謹慎對待。

作為貢獻者，您可以透過自己執行其中一些步驟來幫助推動拉取請求。

1、從正確的人/團隊獲取回饋

生產團隊成員應確保在合併拉取請求之前由合適的人員查看。在某些情況下，這可能需要多人參與。在其他情況下，只需獲得一項實質批准即可合併程式碼。

一般來說，盡量不要僅根據一項評論來合併內容，特別是如果它是您自己的。從另一位維護者那裡獲取第二意見，並確保所有可能受影響的團隊都得到了審核者的合理代表。例如，如果拉取請求新增到檔案中，那麼讓區域維護人員檢查它的事實正確性並讓檔案維護人員檢查它的格式、樣式和語法通常很有用。

一個好的經驗法則是，至少一名主題專家應該批准拉取請求的正確性，並且至少有一名其他維護人員應該批准拉取請求的程式碼樣式。這些人中的任何一個都可能是合併拉取請求的人。

確保審查和批准是由該特定引擎領域的主管人員留下的。即使是戈多組織的長期成員也有可能在不具備相關專業知識的情況下留下評論。

備註

尋找可能已準備好合併的 PR 的簡單方法是按已批准的 PR 進行篩選並按最近更新進行排序。例如，在主 Godot 儲存庫中，您可以使用「此連結 <https://github.com/godotengine/godot/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved+sort%3Aupdated-desc> `_。

2、從社區獲取回饋

如果拉取請求難以吸引審閱者，您可能需要更廣泛地尋求協助進行審查。考慮詢問：

  • 如果拉取請求為他們修復了錯誤，則報告該錯誤的人，

  • 最近編輯過該檔案的貢獻者（如果他們可以看一下），或者

  • 來自其他領域的更有經驗的維護人員（如果他們可以提供回饋）。

3、Git 注意事項

  • 確保 PR 中只有一個提交。

    當每個提交都是獨立的並且可用於建構引擎的乾淨且可工作的版本時，將一個拉取請求與多個提交合併可能是可以的，但一般來說，我們要求所有拉取請求只有一個提交。這有助於我們保持 Git 歷史記錄的乾淨。

  • 評審過程中作出的修改必須 Squash 到主提交中。

    對於多提交 PR，請檢查這些修復是否在相關提交中進行了修改，而不僅僅是應用於所有內容。

  • 確保 PR 沒有合併衝突。

    貢獻者可能需要在相關分支（例如“master”或“3.x”）之上重新調整其更改，並手動修復合併衝突。即使不存在合併衝突，貢獻者也可能需要重新設定特別是舊 PR 的基準，因為 GitHub 衝突屬性面板可能無法捕獲所有衝突，或者 CI 自最初運作以來可能已發生更改。

  • 檢查正確的提交歸屬。

    如果貢獻者使用的作者簽章未在其 GitHub 帳戶中列出，則 GitHub 不會將合併的拉取請求連結到其帳戶。這使他們無法在 GitHub 歷史記錄中獲得適當的榮譽，並使他們在 GitHub UI 上看起來像新貢獻者，即使在多次貢獻之後也是如此。

    最終，使用者是否想要修復該問題取決於使用者，但他們可以透過使用用於GitHub 帳戶的相同電子郵件來編寫Git 提交，或者將用於Git 提交的電子郵件新增到其GitHub 設定檔中來實作此目的。

  • 檢查正確的提交消息。

    雖然我們沒有非常嚴格的提交訊息規則集，但我們仍然要求它們簡短而具有描述性，並使用正確的英語。作為維護者，您可能已經編寫了足夠的程式碼來了解如何製作它們，但對於通用模板，請考慮「修復<程式碼庫的一部分>中的<問題>」*。更詳細的建議，請參閱`contributing.md <https://github.com/godotengine/godot/blob/master/CONTRIBUTING.md#format-your-commit-messages-with-readability-in-mind>` _ Godot 主儲存庫中的頁面。

4、GitHub 注意事項

  • 確認 PR 的目標分支。

    大多數 Godot 開發都發生在「master」分支。因此，大多數拉取請求必須針對它提出。然後，拉取請求可以從那裡向後移植到其他分支。警惕在他們正在使用的版本（例如“3.3”）上製作 PR 的人，並引導他們針對更高階的分支（例如“3.x”）進行更改。如果變更不適用於「master」分支，則可以針對目前維護分支（例如「3.x」）進行初始 PR。人們可以為每個目標分支建立多個 PR，特別是在變更無法輕鬆向後移植的情況下。如果可能的話，挑選櫻桃也是一種選擇。如果可以對 PR 進行挑選（例如“cherrypick:3.x”），請使用適當的標籤。

備註

可以更改已提交的 PR 的目標分支，但請注意後果。由於無法與推送同步，目標分支的變更必然會標記整個維護者列表以供審核。它還可能導致 CI 無法正常運作。推動應該會有所幫助，但如果沒有別的辦法，建議開設一個新的 PR。

  • 確保分配了合適的里程碑。

    如果現在合併拉取請求，這將使哪個版本將包含提交的變更更加明顯。請注意，里程碑不是具有約束力的合同，並且不保證此版本一定會包含 PR。如果在版本發布之前未合併拉取請求，則里程碑將被移動（且 PR 本身可能需要目標分支變更）。

    同樣，當合併具有比目前版本更高的里程碑或「通配符」里程碑（例如「4.x」）的 PR 時，請確保將里程碑更新至目前版本。

  • 確保 PR 消息的開頭包含“Closes #...”或“Fixes #...”咒語。

    這些將 PR 和引用的問題連結在一起，並允許 GitHub 在您合併更改時自動關閉後者。請注意，這僅適用於針對「master」分支的 PR。對於其他問題，您需要關注並手動關閉相關問題。使用 “Fixed by #...” 或 “Resolved by #...” 註解來明確指示未來貢獻者的行為。

  • 為 PR 所關閉的 Issue 新增最近的相關里程碑。

    換句話說，如果 PR 的目標是“master”分支，但隨後也被挑選為“3.x”，則下一個“3.x”版本將是已解決問題的適當里程碑。

更改 PR

如果您適合合併拉取請求（即您是生產團隊的成員或您是該領域的團隊領導），那麼您確信該拉取請求已得到充分審查，並且一旦執行了這些步驟您可以繼續合併拉取請求。