第三方原始碼管理

第三方程式碼包含 Fuchsia 結帳流程，但 Fuchsia 作者和 Fuchsia 的授權均不受版權保護。換句話說，凡是非 Fuchsia 作者擁有的程式碼，都會視為第三方程式碼來管理。

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

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

事前準備

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

語言專屬指南

如要新增 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 的慣例。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: 指令。如此即可確保程式碼長期下來維護相關責任。

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

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

新增 README.fuchsia

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

發表評論

所有第三方新增項目和實質變更 (例如重新授權) 都需要下列簽核：

  • 依照 OSRB 核准中的操作說明接受程式碼審查。
  • 如果第三方專案具備重要的安全性 (如 README.fuchsia 所定義)，請將人員加入 security-dev@fuchsia.dev 來查看變更。

特殊情況

大部分的第三方依附元件都可以遵循上述的版面配置。然而，在不常見情況下，一小部分的依附元件會以不同的方式管理。

使用外來依附元件可能會增加複雜性和維護成本，而這又會由第三方程式碼的直接依附元件造成。此外，這些程式庫也會增加常見的全域維護工作，例如：

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

踏出越重的道路時，請小心審音。

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

把所有現有的 //third_party 程式碼加入上述版面配置，就是 WIP，並歡迎捐款。

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

  1. 將 Fuchsia 專用的 BUILD.gn 檔案移至 //build/secondary。

    1. 將 BUILD.gn 檔案從 //third_party/<name> 複製到 //build/secondary/third_party/<name>。如果有多個 BUILD.gn 檔案，請在 //build/secondary 底下保留相同的子樹狀結構。
    2. 在複製的 BUILD.gn 檔案中，將第三方檔案路徑的參照更新為 //third_party/<name>/ 格式，格式為 //third_party/<name>/src/。
    3. 將 OWNERS 從 //third_party/<name> 複製到 //build/secondary/<name>， 如果不存在，請自行建立。請查看 OWNERS 檔案，確保其符合最佳做法。
    4. 將 README.fuchsia 從 //third_party/<name> 複製到 //build/secondary/<name>。請查看這個檔案的內容，確認中繼資料正確無誤。在罕見的情況下，第三方存放區中的第三方程式碼會經過修改，且這類變更會列在 README.fuchsia 中。根據地區修改內容，通常需要提供本指南未涵蓋的特殊住宿。
    5. 請查看 //third_party/<name> 是否有任何其他第一方 .gni 檔案，並將其移至 //build/secondary/<name>。
    6. 更新 //build/secondary/third_party/<name>/BUILD.gn (和其他包含來源路徑的檔案，例如 .gni 檔案) 以使用新來源位置 //third_party/<name>/src。這需要更新所有來源，包括目錄路徑等。

    範例：https://fxrev.dev/622785

  2. 更新整合資訊清單。

    將 //third_party/<name> 中現有第三方專案的 path (非 name) 替換為 //third_party/<name>/src，同時維持原有修訂版本。合併這項變更後，Fchsia 版本會切換為使用上一個步驟中的 BUILD.gn 檔案。

    範例：http://tqr/457911

  3. 將步驟 1 中新增的 Fuchsia 特定檔案移至 //third_party/<name>。

    現在，第三方程式碼會巢狀結構在 //third_party/<name>/src 底下，//third_party/<name> 屬於 fuchsia.git 的一部分，因此您可以復原轉場效果步驟 1。

    1. 等待整合資訊清單變更合併並擲出，然後執行 jiri update。或者，您也可以在本機結帳中暫存上一個步驟的整合資訊清單變更階段，然後執行 jiri update -local-manifest。

    2. 將 BUILD.gn 和其他 Fuchsia 特定檔案從 //build/secondary/<name> 移至 //third_party/<name>。

    3. 更新 //.gitignore，讓系統追蹤 //third_party/<name>，但不會追蹤 //third_party/<name>/src。

    範例：https://fxrev.dev/622789

  4. 將 //third_party/<name>/src 轉換成鏡像。

    變更 //third_party/<name>/src 以追蹤上游，使其 git log 中只有上游變更。方法是更新整合資訊清單，參照上游修訂版本雜湊。

    範例：http://tqr/427570

延伸閱讀