外部 Rust crates 的審查程序

這裡是因為你需要審查嗎？直接跳至流程 和評論規範。

Rust 的程式庫 (或 Crate) 外部生態系統是 建立提示這個現有程式碼主體可成為 各種規模的團隊，加快並減緩開發風險。

與此同時，外部程式碼就像所有程式碼一樣，都有風險。應該使用 請善用這些 Crate！本文件說明如何將 同時瞭解並盡可能降低風險

背景

建構外部 Rust 程式碼之後，我們的樹狀結構中大約有 100 萬行外部 Rust 程式碼， 包括如何編寫、審查新 Crate 和現有 Crate 的更新 可說是件艱鉅的工作為了在程式碼集中處理 Rust 的規模 現在，我們必須讓所有使用 Rust 的團隊都能審查該團隊的 Crate 都不盡相同

此外，我們也不確定如何審查外部程式碼。 外部程式碼審查與第一方程式碼審查和規範不同 但業界不等多數事實上，許多小型機構 也不會進行外部程式碼審查，完全依賴其他品質信號。

在 Fuchsia 這類專案中，我們無法容許這類風險，因此必須審查程式碼 常用於運送產品與此同時，我們應該將重點放在 ，同時將程序負擔降至最低。

原則

根據風險分配審查工作

時間與心力有限。找出外部程式碼 導入，並集中心力盡量減少這類問題。請比較這些風險與 撰寫新的實作項目

考量未來的費用與效益

遠離塵囂，現在只要做個輕鬆捷徑， 以備不時之需解決更多一般的問題時，可能會重複發生 在整個專案生命週期內分配到的福利

注意驚喜

請記住，我們會花一分錢處理不易理解的程式碼 多次更新 API

沒有預設結果

無論決定使用外部程式碼，以及 考慮採用負責任的 AI 技術做法

回饋金

開放原始碼程式庫是本專案的一大優點。審查期間 因此，請將這些評論的詳細資料列入考量，方便外界前往閱讀 專案。

程序

對所有參與者來說，檢查第三方程式碼可能是一大功夫。是 必須遵循向第三方請求 以將負擔和重複作業降到最低

新增或更新外部 Crate

新增或更新外部 Crate 時，需要審查變更 由其他使用者提交：

  1. 跟著 外部 Rust Crate ，將 Crate 加入樹狀結構。不要上傳變更 到 Gerrit 的回覆。
  2. 是否提供新的 Crate，包括依附元件或變更授權 在現有 Crate 的新版本中提出要求 OSRB 核准： 具體做法是指示 Kubernetes 建立並維護 一或多個代表這些 Pod 的物件
  3. 在獲得 OSRB 核准任何新 Crate 後，請將變更上傳至 Gerrit。 請務必執行下列動作：
    • Cite OSRB 核准訊息中的錯誤。
    • 將第一方程式碼變更與外部程式碼變更分開：
    • 如果 Crate 需要更新多個遞移依附元件 可以考慮使用 cargo update敬上 將遞移更新批次處理成一或多個批次，以減少 CL 大小為減輕審查負擔，我們未用到的依附元件 都是由支援的平台 並透過 Cargo 的資訊清單修補功能，產生空白 Crate。
  4. 將審查人員新增至 CL。任何使用者 (包括您自己！) 都可以查看， 請參閱本節和以下規範。
    • 也可以在 Fuchsia 的 #rust 管道中提問，即可找到審查人員 可找到 Fuchsia 鄉村風的 Discord 或其他聊天室。
    • 如果審查時需要特定領域的專業知識 (例如不安全) 程式碼)，尋找具有該專業知識的審查人員。
    • 請務必讓審查人員知道接受審查的 Crate。個人中心 則可將 Crate 指派給個別審查員，藉此處理大型 CL。
  5. 檢查完所有程式碼後，請新增 rust_crates OWNERS 進行最終審核1。該公司的工作是確保整個程序已順利完成 正確追隨，這應該在 CL 註解中明確提供支援。演唱 主動協助確保快速核准。

查看外部 Crate

有人向您申請審查時，請務必：

  1. 根據評論規範檢查程式碼， 做出最佳判斷，必要時尋求外部協助。
  2. 在程式碼上留言，指出您評論了哪些 Crate。記下您的任何疑慮 以及該評論的注意事項請記下任何令人意想不到的行為或錯誤 內嵌。一般而言，請留意任何風險，即便不認為這些風險 區塊合併
    • 在 CL 層級註解的最上方，先說明哪些 Crate 和版本
    • 如果審查時發現任何警告或風險，請使用星號標示。 請說出「all crates」來精簡這內容或「所有 Crate，但...」 因此擁有者可以快速瀏覽留言 通過核准。
  3. 如果程式碼可以合併，請新增「程式碼審查 +1」。如果您找到 重大錯誤或其他紅色旗標，新增「程式碼審查 -1」以及視需要 建議解決方法，例如：
    • 在合併前修補 Crate 上游。
    • 關閉 CL，並且尋找替代方案。
    • 如果有問題的程式碼位於未用於 Fuchsia 支援的平台 更換 Crate 沒有內容

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

  1. 確認符合評論規範的證據 然後是 CL：
    • 詳閱 新增或更新外部 Crate 以確保您可以受到追蹤
    • 請盡可能從 CL 發表意見，改用非正式溝通。 會留下稽核追蹤記錄
    • 如果缺少證據，請要求 CL 擁有者完成審查程序 請參閱這份文件
  2. 檢視審查人員留意的所有風險：
    • 視需要要求進一步說明。
    • 提及任何應封鎖合併或進一步保固的問題 則討論。新增「程式碼審查 -2」以免 CL 未合併 以便解決這些問題
  3. 按適當的指南操作後，所有風險都會 且您可以放心合併，新增「程式碼審查 +2」。

詳閱指南

外部 Crate 審查最多可包含四項主要元素：

  • 架構審查會大範圍評估外部程式碼 設計為顯而易見如要解決關聯問題，可用 Apriori 這類關聯規則學習技術和演算法
  • 「品質審查」為新推出的 Crate 提供額外審查。
  • 程式碼審查著重於驗證程式碼的正確性。
  • OSRB 核准可確保我們新增的程式碼符合 Fuchsia 的 授權政策OSRB 核准是獨立的程序，必須 再上傳介紹外部程式碼的變更清單

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

Crate 動作 需審查架構 需接受品質審查 必須審查程式碼 須接受 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 包含未記錄的變數 (尤其是不安全的程式碼)， 風險極高

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

新供應商 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 即可取消資格。這些信號應該有助於填補缺少的資料缺口 保持信心及謀求平衡，在模糊不清的情況下取得平衡：

  • 多個維護人員
  • 知名作家
  • 廣泛使用的反向依附元件
    • 這些清單會列在「相依項目」下方。
  • 存放區和 Issue Tracker 中的活動

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

審查外部程式碼時，請根據現有程式碼採用新的 Crate 或進行更新：

留意風險

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

  • unsafe 程式碼
    • 請只在必要時使用不安全的程式碼。應該要能 容易追蹤和/或記錄這些不變體及其運作方式 以保留不變不安全的 API 應很少出現，而且務必將 導致呼叫端必須保持不變的不變2。
  • 需要專業領域知識才能瞭解的程式碼
    • 如果可以，請尋求網域專家檢查此程式碼。範例包括 不安全、低階原子與並行、密碼編譯和網路 通訊協定實作項目
  • 用於重要路徑的程式碼
    • 包括密碼學等重要安全防護路徑 攸關效能的路徑請特別注意這段程式碼 避免損害關鍵路徑
  • 程式碼過於複雜
    • 慣用的 Rust 會使用適當的抽象層級 及輸入系統管理不變體如果程式碼難以達成 會循序漸進地繼續前進，讓您有信心這些不變性 這些元件可能品質低劣 而且含有可避免的錯誤

一如以往，請務必記住替代方案。假設我們需要這個 但當編寫程式碼時 自己？這麼做確實可以產生更好的結果 您會耗費多少心力編寫與維護程式碼？

確認內容正確無誤，但可別過度使用。

在理想情況下，我們能夠正式驗證所有 相關知識這通常不是實際可行的，因此我們必須充分利用 需要投入大量時間與心力，同時提升自己的信心 不斷推陳出新請盡力達成以下目標：

  • 確認導入方式是否合理
    • 參考函式簽章、特徵等。
  • 尋找驚喜
    • 請務必記下 CL 註解中找到的任何資訊 (最好是內嵌在 出現出乎意料的程式碼)
  • 請專注在前方的程式碼
    • 可以假設其他函式執行了他們說的內容，因為您 我們最後仍會審查這些內容不應追蹤整個函式呼叫圖表 而這通常是壞事。請盡可能使用正確 以便集中心力。
  • 請確認 build.rs 變更已反映在版本中
    • build.rs 指令碼無法在我們的版本中執行，但需要翻譯 因此能自動挑選最合適的參數cargo-gnaw 僅提供部分支援，但不支援 可能沒有漏網之魚查看這些變更並驗證所有內容 都會反映在建構規則中如果您不 熟讀這些文件，請要求 CL 擁有者找到另一位審查者 。

略過無關內容。

您不需要檢查下列項目：

  • 程式碼樣式
  • 已審查且未變更的程式碼
  • 個別測試案例和基準
  • 我們保證平台上絕不會用於特定平台專屬程式碼3
  • 無法直接幫助瞭解 API 介面的說明文件 並適度導入

評估新 Crate 的品質時，有些仍相關 。

更多閱讀資訊

  1. 不久後 預計將 Rust 第三方 Crate 指派更精細的擁有權 以便將 Crate 升級作業交由更廣大的集合 規模。↩

  2. 另請參閱 危險網頁指南 都沒有問題↩

  3. 我們支援 Fuchsia、Linux 和 Mac，並且應該支援 Windows 某個部分部分 Rust 程式碼也會針對 wasm 目標編譯。 ↩