本頁面由 Cloud Translation API 翻譯而成。

外部 Rust crates 的審查程序

因為您需要進行審查嗎？請直接跳到相關程序和審核規範。

Rust 的程式庫 (Crates) 外部生態系統是使用語言帶來巨大的優勢。這個現有程式碼的主體可以為任何團隊的團隊執行力倍增，以加速和減風險開發。

此外，如同所有程式碼，外部程式碼也有風險。我們應該使用外部 Crate，但請謹慎使用！本文件說明如何充分運用優勢，同時也能理解並盡可能降低風險。

背景

在編寫時，我們在樹狀結構中嵌入約 100 萬行外部 Rust 程式碼，對新的 Crate 和現有 Crate 的更新進行程式碼審查也相當可觀。為了因應現今程式碼集的 Rust 規模，我們必須協助使用 Rust 的任何團隊審查團隊依賴的 Crate。

此外，我們也不確定如何審查外部程式碼。外部程式碼的評論與第一方程式碼審查不同，業界的標準不佳。事實上，許多小型機構根本不會審查外部程式碼，完全仰賴其他品質信號。

在 Fuchsia 這類專案中，我們無法容許這類風險，因此必須審查用來運送產品的程式碼。同時，我們也應將重心放在盡可能將處理程序負擔降到最低

原則

依據風險分配審查作業

時間和心力有限，找出外部程式碼可能帶來的重大風險，然後集中心力盡量減少這類風險。並將這些風險與編寫新實作者進行比較

考量日後的費用和福利

現在只要仔細想想，今天便利的捷徑就可能成為一大問題。從現在解決更廣泛的問題類型，在專案生命週期內可能會獲得重複的好處。

小心意外的驚喜

請注意，我們會不斷支付清除複雜程式碼或其 API 的費用。

沒有預設結果

這些原則全都適用於決定使用外部程式碼，「以及」自行實作的決定。

回饋

開放原始碼程式庫是專案的主要優勢。審查時，請確保相關詳細資料可供專案以外的人員存取且清晰易讀。

程序

審查第三方程式碼對每位成員來說可能很繁瑣。請務必按照要求與執行第三方審查的程序，將負擔和重複作業的費用降到最低。

新增或更新外部 Crate

新增或更新外部 Crate，且需要他人審查變更時：

按照外部 Rust crate 說明文件，將 crate 新增至樹狀結構。請先不要將變更上傳至 Gerrit。
如果有任何新的 Crate，包括依附元件或變更現有 Crate 中的授權異動，請要求這些 Crate 取得 OSRB 核准。
收到 OSRB 核准任何新 Crate 後，請將變更上傳至 Gerrit。請務必採取以下做法：
- 修訂訊息中的 Cite OSRB 核准錯誤。
- 在可能的情況下，將第一方程式碼變更和外部程式碼變更分開。
- 如果 Crate 需要更新許多遞移依附元件，請考慮使用 cargo update 將遞移更新批次轉換為一或多個批次，以減少 CL 大小。如要降低審查負擔，您可以將未用於我們支援平台的依附元件，透過 Cargo 的資訊清單修補功能取代空白 Crate。
將審查者新增至 CL。只要瞭解這個部分和下列規範，任何人 (包括你！) 都可以審查內容。
- 如果想尋找審查人員，請到 Fuchsia Diiscord 或其他可找到富希斯亞風琴的聊天室的 #rust 管道提問。
- 如果評論需要特定領域專業知識 (例如不安全的程式碼) 才能審查，請尋找具備該專業能力的審查人員。
- 請務必讓評論者知道他們需要審核哪些 Crate。您可以指派 Crate 給個別審查人員，協助他們處理大型 CL。
所有程式碼都審查完畢後，請新增其中一個 rust_crates OWNERS 以進行最終核准¹。此工作是確保相關程序已正確遵循，CL 註解中應清楚支援。主動採取行動有助於確保快速核准。

查看外部 Crate

如果有人要求您審查，請務必：

請根據審查指南檢查程式碼，並視情況執行最佳判斷，並在必要時尋求外部協助。
在程式碼上加註，指出您檢閱了哪些 Crate。請記下您對該則評論的疑慮及相關注意事項。請留意內嵌的任何令人驚訝的行為或錯誤。一般來說，即使您認為不應該封鎖合併，也不會有任何風險。
- 在 CL 層級留言的最上方註明您審核過的 Crate 和版本。
- 如果評論中註明瞭任何警告或風險，請使用星號。您可以藉由說出「all crates」(所有 Crate) 或「all crates 除外...」(所有 crate 除外) 來縮寫，這樣 OWNERS 可以快速略過註解，再將最後的核准給予核准。
如果程式碼看起來可以合併，請新增「程式碼審查 +1」。如果發現重大錯誤或其他紅色旗標，請新增「程式碼審查 -1」，並視需要建議解決方法，例如：
- 在合併之前修補 Crate 上游。
- 關閉 CL 並尋找替代方案。
- 如果違規程式碼位於未用於 Fuchsia 支援的平台的依附元件，則可以使用 Cargo 的資訊清單修補功能將 Crate 替換成空白程式碼。

核准外部新增或更新 (OWNERS)

找出 CL 遵循評論規範的證據：
- 請查看新增或更新外部 Crate 的程序，確保其已遵循。
- 請盡可能使用 CL 上的註解進行非正式通訊，因為註解會留下稽核追蹤記錄。
- 如果缺少證據，請要求 CL 擁有者完成審查程序，並請對方參閱這份文件。
查看審查人員標示的風險：
- 視需要要求說明。
- 請提及任何應封鎖合併或擔保進一步討論的問題。新增「程式碼審查 -2」，確保在解決這些問題前，不會合併 CL。
確實遵守規範後，所有風險就會接受，而您可以放心地合併程式碼，新增「程式碼審查 +2」。

詳閱指南

外部 Crate 審查作業最多涉及四個主要元件：

架構審查會以整體性來評估外部程式碼，目的是找出「明顯」的問題。
品質審查能為新推出的 Crate 提供額外審查。
程式碼審查著重於驗證程式碼的正確性。
OSRB 核准可確保我們新增的程式碼符合 Fuchsia 的授權政策。OSRB 核准程序獨立，必須先完成，才能上傳導入外部程式碼的變更清單。

所需元件取決於變更的性質：

建立動作	需要審核架構	需要審查品質	必須接受程式碼審查	需要 OSRB 審查
已新增為 Cargo.toml 中的直接依附元件	✅	✅	✅	✅
做為其他 Crate 的間接依附元件	❌	✅	✅	✅
更新版本	❌	❌	✅	授權變更時*

* 更新外部 Crate 時，只有在授權變更時 (包括每個檔案授權變更) 才需要 OSRB 核准。

Fuchsia 程式碼使用的 Crate 架構審查

架構審查旨在找出「明顯」的問題，因此適用於輕量級。如果從建築結構的角度無法確定 Crate 是否合理，請在 CL 上註明，以便作者與審查人員做出最終判斷。

新增要樹狀結構內使用的直接依附元件 (也就是直接列於 Cargo.toml 資訊清單中) 時，新使用者和審查人員應思考下列問題：

樹木中是否有類似的 Crate，可供人改用？
這個 Crate 會提取多少依附元件？這些依附元件有多大？
檢查及更新這些依附元件的成本是否與使用 crate 創造的利益不成比例？
以我們的架構來說，這個 Crate 是否合理？而對於在 Fuchsia 目標上執行的程式碼：
- 是否可在非同步情境中使用？(例如，API 是否需要封鎖語意？)
- 這個 Crate 是否大量仰賴 POSIX 模擬？
這個 Crate 有合理的 API，且具備充足的說明文件嗎？
- 如果 API 相當簡單且能自行察覺，則只需提供少量說明文件。
- 如果 API 含有複雜的抽象化機制，則缺乏說明文件會產生費用。
- 如果 API 沒有記錄不變且特別不安全的程式碼，這類 API 具有高風險。

請注意，這些問題不適用於我們不會直接使用的遞移依附元件。當現有的遞移依附元件升級為直接依附元件時，我們應詢問並回答這些問題。

為新廠商的 Crate 進行品質審查

除了下列審查規範外，審查人員也應額外考量新的 Crate，包括供我們直接使用，或做為其他 Crate 的依附元件。

確認 Crate OSRB 已獲核准。

思考未來情況。

請思考我們和 Crate 之間的關係可能會如何改變。

審查這個 Crate 及其依附元件，是否值得採用其 API 的好處？

此外，也請考量未來更新項目的審查成本。

這個 Crate 還可以在哪些其他情境中使用？

我們不會針對每次新使用情況重新審核導入結果。如果您認為 Crate 應該只用於特定平台，或是基於這些假設進行檢查，請在 Cargo.toml 的註解中說明。

某些 Crate 並並不安全，避免在所有可能的情況下使用，例如在特定平台中。如有任何環境使用 crate 並不安全，因此我們必須修改建構內容，以免 Crate 用於其中。否則無法匯入 Crate。

如果維護人員放棄 Crate，會發生什麼情況？

這是否願意自行創立並維護？

注意品質信號：

您可以使用 crates.io 或通常從該存放區連結的來源存放區，找到所有這些品質信號。

第一順位訊號是我們直接證明 Crate 品質的直接證據：

程式碼審查
- 程式碼審查是最基本的優先信號。雖然您必須接受程式碼審查，但幾乎絕非如此。
測試
- 沒有 crate 進行測試的紅色旗標。測試不必全都需要接受審查，但建議您進行一些測試，找出有意義的語意檢查和涵蓋範圍。此外，也要檢查 Crate 的測試是否通過其 CI，或是否使用 cargo test 進行本機結帳。妥善的測試就是一種很好的跡象。

第二順位信號能夠間接證明 Crate 的品質，應做為佐證證據。缺少第二順位信號不應使用 crate。反之，這些信號應有助於填補信心缺口，在模糊化時取得平衡：

多位維護人員
知名作家
妥善使用的反向依附元件
- 這些元件會列在 crates.io 的「依附元件」下方。
存放區和 Issue Tracker 中的活動

所有外部程式碼的程式碼審查

查看外部程式碼時，如果是新的 crate 或更新現有程式碼：

留意風險

外部程式碼存在的常見風險包括：

unsafe 組代碼
- 請只在必要時使用不安全的程式碼。應易於遵循和/或記錄其不變性和保留方式。不安全的 API 應該非常罕見，而且必須一律記錄呼叫端必須維護的不變性 API²。
  
  外部 Crate 中的不安全程式碼必須由不安全的 Rust 程式碼審查人員審查。詳情請參閱「要求進行不安全的程式碼審查」。
程式碼需要專業領域專業知識才能瞭解
- 如果可以，請向網域專家洽詢這個代碼。範例包括不安全的、低階原子和並行、密碼編譯和網路通訊協定實作。
僅供重要路徑使用的程式碼
- 包括密碼編譯等安全性重要路徑，以及攸關效能的路徑。請特別留意這個程式碼，確保程式碼不會入侵重要路徑。
過於複雜的程式碼
- 慣用型 Rust 可利用適當的抽象層級，盡可能使用類型系統管理不變性。如果程式碼難以跟隨，卻讓您確信相關不變量經過妥善管理，則可能是品質偏低，且含有可避免的錯誤。

如同以往，請務必記住我們的替代方案。假設我們需要這項功能，如果自行編寫程式碼，是否會面臨相同的風險？這麼做其實可以產生更優質的結果，是否值得您編寫及維護該程式碼？

驗證正確無誤，但不要過度。

在理想情況下，我們可以正式驗證所有使用的外部程式碼。但這通常不太實際，因此我們需要善用時間和工作來提高信心，同時繼續推動程序。請盡力達成以下目標：

確認實作方式是否合理
- 考量到函式簽章、特徵等。
尋找驚喜
- 請務必記下您在 CL 註解中看到的內容 (最好內嵌於令人意想不到的程式碼)。
將注意力放在前方的程式碼
- 因此，您可以假設其他函式會執行其所說的內容，因為您最終會查看它們。您並不需要追蹤整個函式呼叫圖表，但這種狀況通常都是不對的。請發揮最佳判斷，專注在工作上。
確保 build.rs 變更已反映在建構作業中
- build.rs 指令碼不會在我們的版本中執行，但需要在廠商 Crate 時進行翻譯。cargo-gnaw 對這項功能提供有限支援，但無法擷取所有資訊。請檢查這些變更，確認與建構作業相關的任何內容都已反映在建構規則中。如果您無法查看這些內容，請要求 CL 擁有者尋找其他評論者。

跳過無關的內容。

您不必查看下列項目：

程式碼樣式
已審查的未變更程式碼
個別測試案例和基準
我們相信，絕不會在平台上使用平台專屬程式碼³
說明文件無法直接解讀 API 介面，且實作方式不夠完善，因此無法查看

評估新 Crate 的品質時，其中部分仍具關聯性，如前文所述。

要求審查不安全的程式碼

為了確保 Fuchsia 建構在聲音聆聽的外部程式碼，我們會徹底審查外部 Crate 中的所有不安全的程式碼。不安全的程式碼通常需要特殊的專業知識才能審查，因此當 crate 新增或更新不安全的程式碼時，程式碼必須經過不安全的審查人員核准。

如何申請不安全的程式碼審查：

使用「Unsafe review for external crate」範本回報錯誤並填寫資訊：
- 標題中直接依附的已修改 Crate。
- CL 的評論連結。
- CL 的上傳日期。
- 已變更的行總數 (位於 Gerrit 檔案清單底部)。
- 已新增或更新的選民 Crate。
- 請參考這個範例。
將「Fuchsia Rust Unsafe Review fuchsia-rust-unsafe-reviews@google.com」新增為 CL 的評論者。系統會隨機選擇一名審查人員，並指派對方指派給您的 CL。

如果您的審查具時效性，請提高問題的優先度，並留言說明您的情況。