LLVM 程式碼審查政策與實務

LLVM 的程式碼審查政策與實務有助於維持整個專案的高程式碼品質。具體來說，我們的程式碼審查流程旨在

  • 提高可讀性和可維護性。

  • 提高穩健性並防止引入缺陷。

  • 為每個提議的變更充分利用其他貢獻者的經驗。

  • 透過社群領導者的指導，幫助培養和發展新的貢獻者。

所有貢獻者都必須了解我們的程式碼審查實務並參與程式碼審查流程，這一點非常重要。

一般政策

哪些程式碼應該被審查？

所有開發者都必須在將重大變更提交到儲存庫之前進行審查。

程式碼在提交之前是否必須經過審查？

程式碼可以在提交之前或之後進行審查。我們希望在提交之前對重大修補程式進行審查。較小的修補程式（或開發者擁有該元件的修補程式），如果符合可能的社群共識要求（適用於所有修補程式核准），則可以在明確審查之前提交。如果存在任何不確定性，則應在提交之前對修補程式進行審查。

請注意，負責修補程式的開發者也有責任進行所有必要的審查相關變更，包括在任何提交後審查期間要求的變更。

程式碼在提交後是否可以進行審查？

鼓勵進行提交後審查，並且可以使用以下任何詳細說明的工具來完成。我們強烈希望作者對提交後的回饋意見做出迅速回應並加以處理。如果未能做到這一點，將導致修補程式被 還原。

如果社群成員對最近的提交表示擔憂，並且這種擔憂在提交前審查期間足以引起討論（包括圍繞是否需要更多設計討論），他們可以要求還原給原始作者，而原始作者有責任迅速還原修補程式。開發者經常意見不一，而傾向於要求更多審查的開發者，可以防止對程式碼樹中程式碼的任何揮之不去的分歧。這並不表示修補程式作者有任何錯誤，這是我們提交後審查實務中固有的。還原修補程式可確保在不阻礙其他開發的情況下進行設計討論；一旦解決了擔憂，修補程式完全有可能最終會按原樣重新套用。

在重新提交之前，修補程式通常應 undergo 進一步的審查。發現問題的社群成員應積極參與審查。如果問題是由建置機器人發現的，則應由可以存取與建置機器人類似硬體的社群成員參與審查。

請注意：提交後回饋的標準並不高於提交前回饋。請勿不必要地延遲提供回饋。但是，如果您在程式碼提交後發現了一些您在提交前會評論的事情（如果您之前沒有注意到），請隨時提供回饋。

話雖如此，如果自原始變更提交以來已經過去了相當長的一段時間，那麼最好創建一個新的修補程式來解決問題，而不是對原始提交進行評論。例如，原始修補程式作者可能不再是項目的活躍貢獻者。

使用什麼工具進行程式碼審查？

提交前回饋是在 GitHub 上使用提取請求進行的。請參閱GitHub文件。

什麼時候需要 RFC？

某些變更過於重大，僅憑程式碼審查是不夠的。應該變更 LLVM 語言參考（例如，添加新的與目標無關的內部函式）、在 Clang 中添加語言擴展等變更，首先需要在項目的 *-dev 郵件列表中發送 RFC（徵求意見稿）電子郵件。對於承諾會對使用者和/或下游程式碼庫產生重大影響的變更，審查者可以要求在進行程式碼審查之前達成共識的 RFC。話雖如此，發布初始修補程式可以幫助討論 RFC。

程式碼審查工作流程

程式碼審查可以是一個迭代過程，一直持續到修補程式準備好提交。具體來說，一旦修補程式被發送出去審查，在提交之前需要明確的批准。不要假設默認批准，也不要設定截止日期來徵求對修補程式的反對意見。

備註

如果您將提取請求用於審查以外的目的（例如：預提交 CI 結果、基於 Web 的便捷還原等），請將skip-precommit-approval標籤添加到提取請求。

確認所有審查者的回饋

修補程式作者應確認審查者的所有評論。一般預計，建議的變更將被納入修補程式的未來版本中，除非作者和/或其他審查者能夠清楚說明不這樣做的充分理由（並且審查者必須同意）。如果新的修補程式沒有解決所有未解決的回饋，則作者在提供更新的修補程式時應明確說明。使用基於 Web 的程式碼審查工具時，此類註釋可以在「差異」描述中提供（這與用於提交訊息的「差異修訂」的描述不同）。

如果您在程式碼審查中建議進行變更，但不想讓建議被如此強烈地解讀，請明確說明。

備註

回覆審查者的評論後，請按一下重新請求審查，以提醒審查者注意提取請求。

目標是有效利用每個人的時間

目標是限制審查過程中的迭代次數。例如，在建議變更時，如果您希望作者在程式碼的其他地方進行類似的變更，請說明要求的變更集，以便作者可以一次性完成所有變更。如果修補程式在批准之前需要多個步驟（例如，拆分、重構、發布特定效能測試的數據），請盡可能提前說明這些步驟。這使得修補程式作者和審查者能夠最有效地利用他們的時間。

LGTM - 修補程式如何被接受

當審閱者接受修補程式時，該修補程式就會被核准提交，這幾乎總是與包含文字「LGTM」（代表「我看起來不錯」）的訊息相關聯。只需要一位審閱者的核准。

在提供無條件的 LGTM（核准提交）時，審閱者有責任審閱所有審閱者的所有討論和回饋，確保所有回饋都已得到處理，並且幾乎可以肯定所有其他審閱者都對核准的修補程式感到滿意。如果不確定，審閱者應提供有條件的核准，（例如，「LGTM，但請等待 @someone、@someone_else」）。如果您相當確定某個社群成員希望審閱，即使該成員尚未這樣做，您也可以這樣做。

請注意，如果審閱者已要求特定社群成員進行審閱，並且在一週後該社群成員尚未回覆，請隨意 ping 該修補程式（字面意思是提交對該修補程式的評論，並附上「Ping」一詞），或者，向原始審閱者尋求進一步的建議。

如果其他人可能會想要審閱最近發布的修補程式，特別是如果可能會有反對意見，但還沒有其他人這樣做，那麼提供有條件的核准也是禮貌的（例如，「LGTM，但請等待幾天，以防其他人想要審閱」）。如果很快收到核准，修補程式作者也可以選擇在提交之前等待（對於非平凡的修補程式，這當然被認為是禮貌的）。特別是考慮到我們社群的全球性，這段等待時間至少應為 24 小時。還請注意週末和主要節假日。

我們的目標是確保社群對設計決策和重要的實作選擇達成共識，而審閱者在提供對修補程式的整體核准時，其中一項責任是合理地確定存在這種共識。如果您對社群不夠熟悉，不知道這一點，那麼您不應該提供最終核准來提交。提供最終核准的審閱者應具有 LLVM 專案的提交權限。

每個修補程式都應由受變更影響的專案領域中至少一位技術專家進行審閱。

拆分請求和有條件的接受

審閱者可能會要求將修補程式的某些方面分解成單獨的修補程式，以便進行獨立審閱。審閱者也可以接受以作者提供後續修補程式來解決某些特定問題或疑慮為條件的修補程式（儘管沒有任何已提交的修補程式應使專案處於損壞狀態）。此外，審閱者可以接受以作者在提交之前應用一些次要更新為條件的修補程式，並且在適用的情況下，審閱者這樣做是禮貌的。

不要無意中阻止審閱

如果您審閱了一個修補程式，但並不想讓審閱過程阻塞在您的核准上，請明確說明。出於禮貌，我們通常會等到所有審閱者都滿意後才會提交修補程式，如果您不打算在適當的時間內再次查看該修補程式，請在審閱中說明這一事實。

誰可以/應該審閱程式碼？

非專家也應該審閱程式碼

您不需要成為程式碼庫某個領域的專家才能審查修補程式；您可以隨意詢問任何一段程式碼的作用。 如果您不清楚發生了什麼事，您不太可能是唯一一個這樣做的人。 請記住，從長遠來看，只有少數人能夠清楚理解元件，這不符合社群的最佳利益。 額外的註釋和／或測試案例通常會有所幫助（在測試案例中要求註釋也是可以的）。

此外，我們鼓勵作者將問題視為重新審視相關程式碼可讀性的理由。 結構性變更或進一步的註釋可能會有幫助。

如果您是 LLVM 社群的新手，您也可能會發現這段簡報很有幫助： .. _如何為 LLVM 做出貢獻，2019 年 LLVM 開發者大會簡報： https://youtu.be/C5Y977rLqpw

對於新的貢獻者來說，增加對程式碼庫知識的一個好方法是審查程式碼。 審查程式碼並明確地將批准決定交由他人處理是完全可以接受的。

專家應該審查程式碼

如果您是受建議修補程式影響的編譯器領域的專家，則強烈建議您審查程式碼。 如果您是相關的程式碼擁有者，並且沒有其他專家正在審查修補程式，則您必須協助安排專家審查修補程式或自行審查。

程式碼審查、速度和互惠

有時程式碼審查所需的時間會比您預期的要長，尤其是對於較大的功能。 加快修補程式審查時間的常見方法包括：

  • 審查其他人的修補程式。 如果你願意伸出援手，每個人都會更願意為你做同樣的事；善意是我們的貨幣。

  • 提醒修補程式。 如果情況緊急，請說明為什麼將此修補程式納入對您來說很重要的原因，並每隔幾天提醒一次。 如果不急，一般的提醒頻率是一週一次。 請記住，您正在向其他專業開發人員索取寶貴的時間。

  • 在 IRC 上尋求幫助。 IRC 上的開發人員將能夠直接為您提供幫助，或告訴您誰可能是合適的審查者。

  • 將您的修補程式拆分為多個相互依賴的較小修補程式。 您的修補程式越小，其他人快速瀏覽的可能性就越高。 在執行此操作時，最好在系列中每個修補程式的標題中添加「[N/M]」（對於 1 <= N <= M），以便清楚地表明存在順序以及順序是什麼。

開發人員應同時以審查者和作者的身份參與程式碼審查。 如果有人願意審查您的程式碼，您也應該為其他人做同樣的事。 請注意，歡迎任何人審查修補程式並提供意見回饋，但修補程式的批准應符合上述政策。