第三方原始碼管理

第三方程式碼是 Fuchsia 結帳程序的一部分，但既不受 Fuchsia 作者的著作權保護，也不適用 Fuchsia 的授權條款。換句話說，凡是不完全屬於 Fuchsia 作者的程式碼，都會視為第三方程式碼進行管理。

Fuchsia 專案會在結帳時，將第三方程式碼依附元件的副本保留在 //third_party/ 目錄下。這也稱為「供應商」。供應商可確保第三方程式碼是從 Fuchsia 擁有的來源存放區提供，且提供的修訂版本已知可與 Fuchsia 結帳中的其他程式碼搭配運作。

新增第三方程式碼時，請按照下列步驟操作，確保程式碼符合 Fuchsia 專案政策。

事前準備

所有外部程式碼都必須通過開放原始碼審查委員會 (OSRB) 程序，才能新增至 Fuchsia 平台來源樹狀結構。OSRB 要求核准後，請繼續執行下列步驟。

如果依附元件或子依附元件不會在 Fuchsia 結帳程序中使用，請在 OSRB 要求中指定這項資訊，並說明會透過新增至這個封鎖清單，將其從 Fuchsia 結帳程序中封鎖。如果要在 Fuchsia 結帳中使用，大多會發生授權問題。

特定語言的指南

如要新增 Rust、Go 或 Python 依附元件，請參閱下列指南：

如果是其他語言，請繼續完成下列步驟。

取得程式碼

所有外部程式碼都必須遵循下列 third_party 來源版面配置 (以 googletest 為例)：

root [fuchsia.googlesource.com/fuchsia]
  third_party/
    googletest/
      src/ [fuchsia.googlesource.com/third_party/github.com/google/googletest]
      BUILD.gn
      OWNERS
      README.fuchsia

//third_party/googletest/src/ 是 Fuchsia 擁有的鏡像存放區根目錄，內含 googletest 的上游存放區副本。(注意：如果是 Python 存放區，請將 /src 換成 /<module_name>，以遵循 Python 的慣例。(常見的 Python 工具 (例如 pyright) 預期會採用這項慣例)。

//third_party/googletest/ 目錄是 fuchsia.git 存放區的一部分。

//third_party/googletest/BUILD.gn 定義程式庫的建構目標。googletest由於這個檔案屬於 fuchsia.git (而非 googletest 存放區)，因此可以與其他依附於 googletest 的 Fuchsia BUILD.gn 檔案同步更新。這有助於進行建構重構和其他大規模變更。

如要將第三方程式碼改編為 Fuchsia 專案，可能需要其他檔案，這些檔案會位於 (在本例中) //third_party/googletest 底下。

新增擁有者

每個依附元件都必須有相關聯的 OWNERS 檔案。由於是在 fuchsia.git 中定義，因此可以納入 Fuchsia 專案其他位置的其他檔案擁有者。

OWNERS 檔案必須列出兩個 Fuchsia 開發人員帳戶做為前兩行，或包含指向其他 OWNERS 檔案的 file: 指令。這樣可確保程式碼維護責任不會隨著時間轉移。

除非另有指定，否則 OWNERS 通常是使用依附元件的程式碼擁有者。

依附元件的 OWNERS 可透過下列方式，確保 Fuchsia 和使用者安全無虞：* 在不再需要依附元件時移除 * 在上游修正安全性或穩定性錯誤時更新依附元件 * 確保使用依附元件的 Fuchsia 功能持續以最佳方式使用依附元件，因為功能和依附元件會隨時間改變。

新增 README.fuchsia

您需要 README.fuchsia 檔案，其中包含要重複使用的程式碼所屬專案的相關資訊。如需必填欄位清單，請參閱 README.fuchsia。

取得評論

所有第三方新增內容和重大變更 (例如重新授權) 都需要以下核准：

  • 按照「OSRB 審核」一文中的指示，請 OSRB 審查代碼。
    • 如果依附元件或子依附元件不會在 Fuchsia 結帳程序中使用，請在 OSRB 要求中指定這項資訊，並說明會透過新增至這個封鎖清單，將其從 Fuchsia 結帳程序中封鎖。如果要在 Fuchsia 結帳中使用，大多會發生授權問題。
  • 如果第三方專案對安全性至關重要 (如 README.fuchsia 所定義)，請納入 security-dev@fuchsia.dev 中的人員來審查變更。

特殊情況

大多數第三方相依性都可以遵循上述版面配置。不過，如果依附元件適用於罕見情況，則會以不同方式管理。

如果依附元件較為特殊，可能會增加複雜度和維護費用，而這些費用是由第三方程式碼的直接依附元件產生。此外，這些裝置還會增加常見全球維護作業的複雜度，例如：

  • 執行 Git 管理工作。
  • 更新及維護工具鍊。
  • 從上游來源更新有安全漏洞的第三方程式碼，以因應已揭露的安全漏洞。
  • 重構建構規則，例如強制執行新的編譯時間檢查。

請務必謹慎評估是否要離開主要路線。

將舊版第三方程式碼遷移至目前的版面配置

將所有現有的 //third_party 程式碼帶入上述版面配置是 WIP，歡迎提供貢獻。

如要將舊版第三方存放區遷移至這個版面配置，請按照下列步驟操作：

  1. 更新資訊清單。

    1. 將 //third_party/<name> 中現有第三方專案的 path (而非 name) 替換為 //third_party/<name>/src，同時保留修訂版本。

    2. 更新 //.gitignore，以便追蹤 //third_party/<name>，但不要追蹤 //third_party/<name>/src。

    然後執行 jiri update -local-manifest-project=fuchsia，將專案移至本機結帳的新位置。

  2. 將 Fuchsia 專屬的 BUILD.gn 檔案移至 fuchsia.git。

    1. 將 BUILD.gn 檔案從 //third_party/<name>/src 複製到 //third_party/<name> (現在是 fuchsia.git 的一部分)。
    2. 在複製的 BUILD.gn 檔案中，將第三方檔案路徑的參照從 //third_party/<name>/ 形式更新為 //third_party/<name>/src/ 形式。
    3. 將 //third_party/<name>/src 中的 OWNERS 複製到 //third_party/<name>，或建立 OWNERS (如果不存在)。檢查 OWNERS 檔案，確保符合最佳做法。
    4. 將 README.fuchsia 從 //third_party/<name>/src 複製到 //third_party/<name>。請檢查這個檔案的內容，確保中繼資料正確無誤。在少數情況下，第三方存放區中的第三方程式碼會經過修改，這類變更會列在 README.fuchsia 中。本地修改通常需要您進行本指南未涵蓋的特殊調整。
    5. 檢查「//third_party/<name>/src」是否有其他第一方「.gni」檔案， 並將這些檔案也移至「//third_party/<name>」。
    6. 更新 //third_party/<name>/BUILD.gn (和其他包含來源路徑的檔案，例如 .gni 檔案)，使用新的來源位置 //third_party/<name>/src。這需要更新所有來源，包括目錄路徑等。

  3. 將 //third_party/<name>/src 變成鏡子。

    變更 //third_party/<name>/src 以追蹤上游，這樣 git log 中就只會有上游變更。方法是更新資訊清單，參照上游的提交雜湊。

    範例：http://tqr/427570

  4. 修訂並推送變更。所有這些變更都可以在單一 CL 中完成。

您可以執行 jiri update -local-manifest-project=fuchsia，然後建構 (例如使用 fx build)，在本地驗證變更。

延伸閱讀