第三方程式碼是 Fuchsia 結帳程序的一部分,但不受 Fuchsia 作者的著作權保護,也不適用 Fuchsia 的授權。換句話說,凡是不完全屬於 Fuchsia 作者的程式碼,都會視為第三方程式碼。
Fuchsia 專案會在結帳時,將第三方程式碼依附元件的副本保留在 //third_party/ 目錄下。這也稱為 Vendoring。Vendoring 可確保第三方程式碼是從 Fuchsia 擁有的來源存放區提供,且提供的修訂版本已知可與 Fuchsia 結帳中的其他程式碼搭配運作。
新增第三方程式碼時,請按照下列步驟操作,確保程式碼符合 Fuchsia 專案政策。
事前準備
所有外部程式碼都必須通過開放原始碼審查委員會 (OSRB) 程序,才能加入 Fuchsia 平台來源樹。OSRB 要求核准後,請繼續執行下列步驟。
如果依附元件或子依附元件不會在 Fuchsia 結帳程序中使用,請在 OSRB 要求中指定,並說明會透過新增至這個封鎖清單,將其從 Fuchsia 結帳程序中封鎖。如果要在 Fuchsia 結帳流程中使用,大多會發生授權問題。
新增第三方依附元件時,程式碼擁有者必須確保依附元件保持最新狀態。系統會監控新近度,並在依附元件不符合規定時通知 OWNERS。非語言專屬依附元件的新鮮度是取自各依附元件的 README.fuchsia,尤其是 Revision 和 URL 欄位,詳情請參閱 README.fuchsia 說明文件。
目前,如果依附元件符合下列條件,就會視為最新:
符合新上游版本的更新服務等級目標 (定義如下)。
由上游有效專案維護。
- 有效:最新的上游版本或提交內容發布時間未超過 2 年,且存放區未遭封存或淘汰。
如要申請例外,請提交例外狀況。
之後,第三方依附元件也必須註冊自動推送更新,才能視為最新版本;我們會管理該項要求的個別例外程序。
更新服務等級目標
如果依附元件用於正式版,則必須在 30 天內追蹤上游的依附元件。如果是以版本為準,依附元件必須在 30 天內追蹤次要版本,並在 3 個月內追蹤主要版本。
如果是其他依附元件,以 HEAD 為基礎的依附元件必須在 90 天內追蹤上游。如果是以發布版本為準,依附元件必須在 90 天內追蹤次要版本,並在 1 年內追蹤主要版本。
各語言專屬指南
如要新增 Rust、Go 或 Python 依附元件,請參閱下列指南:
Rust:請參閱外部 Rust Crate 指南。
前往:請參閱
//third_party/golibs/。Python:請參閱外部 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 審核」一節的說明,請人審查程式碼。
- 如果依附元件或子依附元件不會在 Fuchsia 結帳程序中使用,請在 OSRB 要求中指定該項目,並說明該項目會新增至這個封鎖清單,從 Fuchsia 結帳程序中封鎖。如果要在 Fuchsia 結帳中使用,大多會發生授權問題。
- 如果第三方專案對安全性至關重要 (如
README.fuchsia所定義),請在security-dev@fuchsia.dev中加入人員來審查變更。
特殊情況
大多數第三方依附元件都可以採用上述版面配置。不過,有少數依附元件會受到罕見情況影響,因此管理方式有所不同。
如果依附元件較為特殊,可能會增加複雜度和維護費用,而這些費用是由第三方程式碼的直接依附元件產生。此外,這些差異還會增加常見全球維護作業的複雜度,例如:
- 執行 Git 管理工作。
- 更新及維護工具鍊。
- 回應揭露的安全漏洞,方法是從上游來源更新有安全漏洞的第三方程式碼。
- 重構建構規則,例如強制執行新的編譯時間檢查。
請務必謹慎評估是否要偏離既有路線。
將舊版第三方程式碼遷移至目前的版面配置
將所有現有的 //third_party 程式碼帶到上述版面配置是 WIP,歡迎提供貢獻。
如要將舊版第三方存放區遷移至這個版面配置,請按照下列步驟操作:
更新資訊清單。
將
//third_party/<name>中現有第三方專案的path(不是name) 替換為//third_party/<name>/src,同時維持修訂版本不變。更新
//.gitignore,以便追蹤//third_party/<name>,但不追蹤//third_party/<name>/src。
然後執行
jiri update -local-manifest-project=fuchsia,將專案移至本機結帳的新位置。將 Fuchsia 專屬的
BUILD.gn檔案移至 fuchsia.git。- 將
BUILD.gn檔案從//third_party/<name>/src複製到//third_party/<name>(現為 fuchsia.git 的一部分)。 - 在複製的
BUILD.gn檔案中,將第三方檔案路徑的參照從//third_party/<name>/形式更新為//third_party/<name>/src/形式。 - 將
OWNERS從//third_party/<name>/src複製到//third_party/<name>,或建立 (如果不存在)。檢查OWNERS檔案,確保符合最佳做法。 - 將
README.fuchsia從//third_party/<name>/src複製到//third_party/<name>。檢查這個檔案的內容,確認中繼資料正確無誤。在少數情況下,第三方存放區中的第三方程式碼會遭到修改,這類變更會列在README.fuchsia。通常您需要進行特殊調整,而本指南未涵蓋這些調整。 - 查看是否有其他第一方
.gni檔案,並將這些檔案也移至//third_party/<name>。//third_party/<name>/src - 更新
//third_party/<name>/BUILD.gn(和其他包含來源路徑的檔案,例如.gni檔案),使用新的來源位置//third_party/<name>/src。這需要更新所有來源,包括目錄路徑等。
- 將
將
//third_party/<name>/src變成鏡子。變更
//third_party/<name>/src以追蹤上游,讓git log中只有上游變更。方法是更新資訊清單,參照上游的提交雜湊。修訂並推送變更。所有這些變更都可以在單一 CL 中完成。
您可以執行 jiri update
-local-manifest-project=fuchsia,然後建構 (例如使用 fx build),在本機驗證變更。