LLVM 程式碼審查政策與實務¶
LLVM 的程式碼審查政策與實務有助於維持專案的高程式碼品質。具體而言，我們的程式碼審查流程旨在：
提升可讀性與可維護性。
提升穩健性並預防缺陷的引入。
為每個提議的變更，盡可能利用其他貢獻者的經驗。
透過社群領導者的指導，幫助培養和發展新的貢獻者。
所有貢獻者都必須了解我們的程式碼審查實務並參與程式碼審查流程，這點非常重要。
一般政策¶
哪些程式碼應該被審查？¶
所有開發者都必須讓重大變更在提交到儲存庫之前經過審查。
程式碼是否必須在提交前經過審查？¶
程式碼可以在提交前或提交後進行審查。我們期望重大的修補程式在提交前經過審查。較小的修補程式（或開發者擁有組件的修補程式），若符合可能社群共識的要求（適用於所有修補程式批准），則可以在明確審查之前提交。在任何不確定的情況下，修補程式都應在提交前經過審查。
請注意，修補程式的負責開發者也負責進行所有必要的審查相關變更，包括在任何提交後審查期間要求的變更。
程式碼可以在提交後進行審查嗎？¶
鼓勵提交後審查，並且可以使用以下詳述的任何工具來完成。強烈期望作者及時回應提交後的回饋並解決它。未能這樣做將導致修補程式被還原。
如果社群成員對最近的提交表示擔憂，並且這種擔憂足以在提交前審查期間引起討論（包括圍繞需要更多設計討論），他們可以要求原始作者還原，原始作者有責任立即還原修補程式。開發者經常意見不合，並且傾向於要求更多審查的開發者一方，可以防止對程式碼樹中的程式碼產生任何揮之不去的分歧。這並不表示修補程式作者有任何錯誤，這是我們提交後審查實務中固有的。還原修補程式可確保設計討論可以在不阻礙其他開發的情況下進行；一旦問題得到解決，修補程式完全有可能最終以基本相同的形式重新應用。
在重新提交之前，修補程式通常應接受進一步審查。發現問題的社群成員應積極參與審查。如果問題是由建置機器人發現的，則期望具有類似於建置機器人硬體的社群成員參與審查。
請注意：提交後回饋的門檻不比提交前回饋的門檻高。不要不必要地延遲提供回饋。但是，如果您在程式碼提交後發現您會在提交前評論的內容（如果您更早注意到它），請隨時提供該回饋。
話雖如此，如果自原始變更提交以來已經過了相當長的時間，那麼創建一個新的修補程式來解決問題可能比評論原始提交更好。例如，原始修補程式作者可能不再是專案的活躍貢獻者。
程式碼審查使用哪些工具？¶
提交前程式碼審查在 GitHub 上使用 Pull Requests 進行。請參閱 GitHub 文件。
何時需要 RFC？¶
有些變更對於僅僅進行程式碼審查而言太過重大。應該變更 LLVM 語言參考（例如，新增獨立於目標的內建函數）、在 Clang 中新增語言擴展等等的變更，首先需要在 LLVM 討論論壇上發布 RFC（徵求意見）主題。對於承諾對使用者和/或下游程式碼庫產生重大影響的變更，審查者可以要求在繼續進行程式碼審查之前達成 RFC 共識。話雖如此，發布初始修補程式可以幫助進行 RFC 討論。
程式碼審查工作流程¶
程式碼審查可能是一個迭代過程，該過程將持續到修補程式準備好提交為止。具體而言，一旦修補程式被送出以供審查，它就需要明確的批准才能提交。不要假設默認批准，或以截止日期徵求對修補程式的反對意見。
注意
如果您使用 Pull Request 的目的不是為了審查（例如：提交前 CI 結果、方便的基於網路的還原等），請使用 skip-precommit-approval 標籤標記 PR。
確認所有審查者的回饋¶
修補程式作者應確認審查者的所有評論。通常期望建議的變更將被納入修補程式的未來版本中，除非作者和/或其他審查者可以闡明充分的理由不這樣做（然後審查者必須同意）。如果新的修補程式未解決所有未解決的回饋，則作者應在提供更新後的修補程式時明確說明。當使用基於網路的程式碼審查工具時，此類註釋可以在“Diff”描述中提供（這與用於提交訊息的“Differential Revision”的整體描述不同）。
如果您在程式碼審查中提出變更建議，但不希望該建議被如此強烈地解釋，請明確說明。
注意
在回覆審查者評論後，按下重新請求審查，以引起審查者對 Pull Request 的注意。
旨在有效利用所有人的時間¶
旨在限制審查過程中的迭代次數。例如，當建議變更時，如果您希望作者在程式碼的其他位置進行類似的一組變更，請解釋請求的變更集，以便作者可以一次進行所有變更。如果修補程式在批准之前需要多個步驟（例如，拆分、重構、發布來自特定效能測試的數據），請盡可能預先解釋其中許多步驟。這允許修補程式作者和審查者最有效率地利用他們的時間。
LGTM - 如何接受修補程式¶
當審查者接受修補程式時，修補程式被批准提交，這幾乎總是與包含文字 “LGTM”（代表 Looks Good To Me，看起來對我來說不錯）的訊息相關聯。
除非 pull request 有要求的審查者，否則僅需一位審查者的批准。在這種情況下，您必須獲得所有這些審查者的批准。
當提供無條件的 LGTM（批准提交）時，審查者有責任審查所有先前的討論和所有審查者的回饋，確保所有回饋都已得到解決，並且所有其他審查者幾乎肯定會對修補程式被批准感到滿意。如果不確定，審查者應提供有條件的批准（例如，“LGTM，但請等待 @某人, @某人_其他人”）。如果您相當確定特定社群成員希望進行審查，即使該人員尚未這樣做，您也可以這樣做。
如果在接受後提供了額外的回饋（由同一審查者或另一位審查者提供），作者應使用他們的最佳判斷來決定該回饋是否可以在沒有評論的情況下納入變更（例如錯字）或需要進一步的審查討論。更實質性的評論（例如，關於設計的評論）通常需要進一步討論。如果不確定，請詢問審查者。
請注意，如果審查者已請求特定社群成員進行審查，並且在一周後該社群成員尚未回覆，請隨時 ping 修補程式（字面意思是提交帶有“Ping.”一詞的修補程式評論），或者，請原始審查者提供進一步的建議。
如果很可能其他人會想要審查最近發布的修補程式，特別是如果可能存在異議，但還沒有其他人這樣做，那麼提供有條件的批准也很禮貌（例如，“LGTM，但請等待幾天，以防其他人希望審查”）。如果很快收到批准，修補程式作者也可以選擇在提交之前等待（對於非微不足道的修補程式，這當然被認為是禮貌的）。特別是考慮到我們社群的全球性，此等待時間應至少為 24 小時。也請注意週末和主要節假日。
我們的目標是確保社群對設計決策和重大的實作選擇達成共識，並且審查者在為修補程式提供整體批准時，其責任之一是合理地確定存在這種共識。如果您對社群不夠熟悉以至於無法知道，那麼您不應提供最終的提交批准。提供最終批准的審查者應具有 LLVM 專案的提交權限。
每個修補程式都應由至少一位受變更影響的專案領域的技術專家進行審查。
拆分請求和有條件接受¶
審查者可以請求將修補程式的某些方面拆分為單獨的修補程式以進行獨立審查。審查者也可以接受以作者提供後續修補程式來解決某些特定問題或疑慮為條件的修補程式（儘管沒有已提交的修補程式應使專案處於損壞狀態）。此外，審查者可以接受以作者在提交前應用一組小的更新為條件的修補程式，並且在適用的情況下，審查者這樣做是禮貌的。
不要無意中阻止審查¶
如果您審查修補程式，但不希望審查過程因您的批准而被阻止，請明確說明。出於禮貌，我們通常會等待提交修補程式，直到所有審查者都滿意為止，如果您不打算及時再次查看修補程式，請在審查中傳達這一事實。
誰可以/應該審查程式碼？¶
非專家也應該審查程式碼¶
您不需要成為程式碼庫某些領域的專家即可審查修補程式；您可以提出關於某段程式碼在做什麼的問題。如果您不清楚發生了什麼事，您可能不是唯一的一個。請記住，擁有只有少數人能很好理解的組件不符合社群的長遠最佳利益。額外的註解和/或測試案例通常會有幫助（並且要求在測試案例中添加註解也可以）。
此外，鼓勵作者將問題解釋為重新檢查相關程式碼可讀性的理由。結構性變更或進一步的註解可能是適當的。
如果您是 LLVM 社群的新手，您可能也會發現此簡報很有幫助：.. _如何貢獻 LLVM，2019 年 LLVM 開發者會議簡報：https://youtu.be/C5Y977rLqpw
對於新的貢獻者來說，增加他們對程式碼庫的知識的一個好方法是審查程式碼。審查程式碼並明確地將批准決定權交給其他人是完全可以接受的。
專家應該審查程式碼¶
如果您是受提議的修補程式影響的編譯器領域的專家，那麼我們強烈建議您審查程式碼。如果您是相關的維護者，並且沒有其他專家審查修補程式，您必須協助安排專家審查修補程式或自行審查。
程式碼審查、速度和互惠¶
有時，程式碼審查會比您希望的要花費更長的時間，尤其是對於較大的功能。加速修補程式審查時間的常見方法是：
審查其他人的修補程式。如果您伸出援手，每個人都會更願意為您做同樣的事情；善意是我們的貨幣。
Ping 修補程式。如果很緊急，請說明為什麼對您而言盡快提交此修補程式很重要，並每隔幾天 ping 一次。如果不緊急，通常禮貌的 ping 頻率為一周。請記住，您正在向其他專業開發人員索取寶貴的時間。
在 Discord 上尋求幫助。Discord 上的開發人員將能夠直接幫助您，或告訴您誰可能是好的審查者。
將您的修補程式拆分為多個建立在彼此之上的較小修補程式。您的修補程式越小，有人會快速查看它的可能性就越高。執行此操作時，在系列中每個修補程式的標題中添加“[N/M]”（對於 1 <= N <= M）會很有幫助，這樣可以清楚地了解存在順序以及該順序是什麼。
開發人員應以審查者和作者的身分參與程式碼審查。如果有人好心審查您的程式碼，您應該為其他人回報恩惠。請注意，歡迎任何人審查修補程式並提供回饋，但修補程式的批准應與上述政策一致。