第三方原始碼管理

第三方程式碼是 Fuchsia 結帳作業的一部分，但並未由 Fuchsia 作者擁有版權，也不受 Fuchsia 授權規範。換句話說，任何不是由 Fuchsia 作者 100% 擁有的程式碼，都會視為第三方程式碼進行管理。

Fuchsia 專案會在檢查點的 //third_party/ 目錄下維護第三方程式碼依附元件的副本。這也稱為「供應商」。供應商可確保第三方程式碼來自 Fuchsia 擁有的原始碼存放區，且在已知可與 Fuchsia 結帳中的其他程式碼搭配使用的修訂版本中提供。

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

事前準備

所有外部程式碼都必須經過 開放原始碼審查委員會 (OSRB) 程序，才能加入 Fuchsia 平台原始碼樹狀結構。OSRB 申請核准後，請繼續執行下列步驟。

語言專屬指南

如果您要新增 Rust、Go 或 Python 依附元件，請按照下列指南操作：

如要使用其他語言，請繼續完成下列步驟。

取得程式碼

所有外部程式碼都必須遵循下列第三方來源版面配置 (以 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 慣例。這項慣例是 pyright 等常見 Python 工具所預期的。

//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: 指令。這麼做可確保程式碼的維護工作持續進行。

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

依附元件的擁有者可協助確保 Fuchsia 及其使用者的安全，方法如下： * 在不再需要依附元件時/如果不再需要，請移除依附元件 * 在安全性或穩定性錯誤的上游修復時，更新依附元件 * 隨著功能和依附元件隨時間變更，協助確保使用依附元件的 Fuchsia 功能持續以最佳方式使用依附元件。

新增 README.fuchsia

您需要一個 README.fuchsia 檔案，其中包含您要重複使用的程式碼來源專案相關資訊。請參閱 README.fuchsia，瞭解應納入哪些必填欄位。

取得評論

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

  • 按照 OSRB 核准中的指示，讓程式碼接受審查。
  • 如果第三方專案對安全性至關重要 (如 README.fuchsia 所定義)，請將 security-dev@fuchsia.dev 中的某人納入，以便審查變更。

特殊情況

大多數的第三方相依項目都可以遵循上述版面配置。不過，少數依附元件會受到特殊情況影響，因此管理方式有所不同。

使用特殊依附元件可能會增加複雜度和維護成本，而這些成本是由於第三方程式的直接依附元件而產生。此外，這些裝置也會讓常見的全球維護工作變得更加複雜，例如：

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

請謹慎評估是否要離開熱門路線。

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

將所有現有的 //third_party 程式碼納入上述說明的版面配置是正在進行的工作，歡迎提供貢獻。

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

  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. 將 OWNERS 從 //third_party/<name>/src 複製到 //third_party/<name>，或在未存在的情況下建立。查看 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 以追蹤上游，這樣 //third_party/<name>/src 就只會在其 git log 中顯示上游變更。方法是更新清單，以便參照上游的提交雜湊。

    範例：http://tqr/427570

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

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

延伸閱讀