| RFC-0216：Fuchsia 託管存放區指南 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 在 fuchsia.git 以外開發 Fuchsia 代管程式碼的指南 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 2022-1-17 |
| 審查日期 (年-月-日) | 2023-04-20 |
摘要
隨著 Fuchsia 完整支援 Bazel，以及越來越重視功能齊全的 Fuchsia SDK，在 fuchsia.git 中開發 Fuchsia 元件的優勢已大幅減少。本 RFC 說明在其他 Fuchsia 託管存放區中開發元件的需求條件和最佳做法。無法滿足 fuchsia.git 以外的組裝需求。
提振精神
自 Fuchsia 專案啟動以來，大部分的開發作業都是在由 jiri 工具管理的單一環境中進行，這個工具會協調多個原始碼存放區的開發作業，就像這些存放區是單一存放區一樣。如今，我們非正式地將該環境稱為 fuchsia.git，因為 Fuchsia 的大部分開發作業都集中在該存放區。
單一受管理環境 (通常位於單一存放區) 對於開發作業有顯著優勢。程式碼可以在整個程式碼集中快速更新，通常只要進行單一變更即可，因此不需要在不同存放區的版本之間進行複雜的協調。開發人員工具和第三方 / 程式庫程式碼的更新作業可以集中處理，因此整個機構都能享有升級和程式碼清理的好處。常見的程式碼標準可避免因程式碼樣式或目錄版面配置而爭論不休。開發人員知道要搜尋任何指定程式碼的存放區。
不過，集中式存放區無法滿足所有 Fuchsia 開發人員的需求。Fuchsia 存放區要求開發人員建構整個系統映像檔和 SDK，大幅影響開發人員速度。在 fuchsia.git 中建構系統映像檔和 SDK 的需求，意味著許多開發人員的建構體驗大不相同。
或許更重要的是，Fuchsia 團隊會為不使用 fuchsia.git 的開發人員建立抽象概念，但我們自己通常不會使用這些概念。這會為開發人員帶來問題，因為他們在 fuchsia.git 中開始工作時，預期會使用標準 Fuchsia 工作流程，但實際上卻遇到 fx 工具和各種指令碼，這些工具和指令碼與我們提供給以 SDK 為基礎的開發人員的工具和指令碼幾乎完全不同。此外，這也讓 fuchsia.git 開發人員更難以同理 SDK 開發人員，因為他們使用的工作流程不同，因此沒有相同的動機來改善這些工作流程。
Fuchsia 建構團隊正努力解決fuchsia.git架構與 SDK 架構工作流程之間的部分差異，但即使如此，仍會存在一些差距，因為在其他存放區使用 SDK 架構工作流程的開發人員，永遠不必建構 SDK 或系統映像檔做為這些工作流程的一部分。
我們預期近期內不會有所有開發人員將程式碼移至以 SDK 為基礎的工作流程。2023 年，團隊將著重於支援將驅動程式從 fuchsia.git 遷移出來。其他專案則可視需要移出 fuchsia.git。
在短期內，我們預計會將完全以 SDK 型 API 建構的元件，從 fuchsia.git 遷移出去。
為提高不必為 SDK 貢獻的專案開發人員生產力，並增進 Fuchsia 團隊對 SDK 開發人員的同理心，Fuchsia 社群希望鼓勵開發人員在 fuchsia.git 以外使用 SDK 型工作流程。不過，我們沒有明確的指南說明如何執行這項操作。這份 RFC 是根據我們過去幾年使用 SDK 型工作流程和 fuchsia.git 工作流程的經驗編寫，旨在填補這些缺口。
利害關係人
協助人員：
- David Moore (davemoore@google.com)
審查者：
- Adam Barth (abarth@google.com) - FEC
- Chase Latta (chaselatta@google.com) - Bazel 支援
- Nathan Mulcahey (nmulcahey@google.com) - EngProd
- Suraj Malhotra (surajmalhotra@google.com) - Drivers
已諮詢：
下列人員也參與了這份 RFC 的諮詢：
- Andres Oportus (andresoportus@google.com)
- Christopher Anderson (cja@google.com)
- Clayton Wilkinson (wilkinsonclay@google.com)
- Danny Rosen (dannyrosen@google.com)
- Harsh Priya NV (harshanv@google.com)
- Janna Shaftan (jshaftan@google.com)
- John Wittrock (wittrock@google.com)
- Renato Mangini Dias
- Marc-Antoine Ruel (maruel@google.com)
- Nico Haley (nicoh@google.com)
- Niraj Majmudar (nirajm@google.com)
- Seth Ladd (sethladd@google.com)
- Tim Kilbourn (tkilbourn@google.com)
社交：
我們已向 EngProd、FHCP、Drivers、Eng Council、Bazel SDK Integration 和 DevRel 團隊，說明這項 RFC 的簡短版本。
設計
以下是一組指南，說明如何開始開發以 SDK 為基礎的 Fuchsia 託管存放區。以下僅為部分參考示例。舉例來說，我們雖然會提供一些指南，說明如何讓 Fuchsia 託管存放區中的 SDK 維持在最新狀態，但不會詳細說明該程序的設計。
存放區命名
存放區名稱取決於存放區的內容。我們將指引分為驅動程式庫和非驅動程式庫存放區。
驅動程式
不屬於特定供應商的驅動程式代碼應託管在以驅動程式庫區域命名的存放區中 (例如 drivers/audio.git、drivers/wlan.git)。例如鍵盤和滑鼠等一般驅動程式的程式碼。這些存放區也不應包含閉源程式碼。
我們瞭解這些區域的名稱可能會隨時間變更。將存放區移至新路徑可能很困難。建議開發人員慎選區域名稱，並確保日後變更名稱時已完成盡職調查。
特定供應商專屬的驅動程式代碼應託管在 drivers/ 中/drivers/wlan/intel/iwlwifi 是否為獨立存放區，或是否位於 drivers/wlan 存放區)。我們可根據現有經驗提供一些指引，相信隨著時間推移，我們將累積更多相關經驗：
如果驅動程式庫需要封閉原始碼軟體才能建構，建議您將這類驅動程式放在與完全開放原始碼驅動程式不同的存放區。
如果多個驅動程式共用大量程式碼 (請參閱下方的程式碼共用)，將這些驅動程式與該程式碼放在單一存放區，可避免在多個存放區中推出該程式碼更新時遇到困難。在這種情況下，開發人員通常很難找到所有相關存放區、在其中建構軟體，以及測試軟體。對大多數程式碼而言，減少存放區代表您不必花費太多心力，就能掌握程式庫、SDK 和工具鍊的最新更新。
有時多個驅動程式會共用大量程式碼，但情況會決定是否要將這些程式碼保留在個別存放區。如果存放區名稱重疊 (例如
drivers/<area>和drivers/<area>/<vendor>都是存放區)，Gerrit 支援就會很奇怪，而且開發人員想將兩個存放區都簽出到同一個目錄時，重疊可能會造成意外衝突。建議您將通用程式碼放在名為drivers/<area>/common的存放區，而不是drivers/<area>。程式碼可在多位駕駛人需要之前，於一般區域開發，避免程式碼遷移的成本。驅動程式團隊可能會決定從穩定分支版本發布驅動程式以供認證。如果這麼做，他們可能會發現管理一個分支比管理多個分支更容易。Fuchsia 團隊正在制定驅動程式庫認證的最佳做法，這可能成為日後 RFC 的主題。
非驅動程式庫元件
與驅動程式無關的元件原始碼可能會託管在下列兩個位置之一。開發人員可彈性選擇。
元件可能會託管在以贊助該元件的功能領域命名的存放區中 (例如 experiences.git)。如果元件不太可能引起功能領域以外的開發人員興趣，建議您採用這種做法。
元件可能會託管在以專案命名的存放區中 (例如 workstation.git、cobalt.git)。如果專案較大，或是開發人員可能對功能領域以外的專案感興趣，建議使用這種方式。
與驅動程式庫程式碼一樣，共用來源資料庫也有優缺點。該節所述的注意事項也適用於元件。
存放區配置
程式碼版面配置應與 Fuchsia 原始碼版面配置文件相同。必須更新原始碼版面配置文件，以反映 Bazel 建構系統的允許使用情形，也就是允許使用 BUILD.bazel 而非 BUILD.gn，以及存在 WORKSPACE 檔案。
開發人員可以複製基礎範本存放區，建立新的存放區。我們可能會有其他存放區，提供專為驅動程式、元件和產品整合 (如有需要) 設計的工具和版面配置。範本會包含 Fuchsia 存放區所需的基本項目。目前包括授權檔案、具有預先定義目標的 Bazel 建構檔案 (基礎架構可讀取這些目標，瞭解要建構和測試的內容)，以及列出至少兩位擁有者的頂層 OWNERS 檔案。
駕駛人必須通過認證測驗。這項認證計畫稱為 Fuchsia 裝置認證計畫 (Fuchsia Hardware Certification Program，簡稱 FHCP)。託管在 fuchsia.git 中的 FHCP 測試應位於相關來源區域的 tests/conformance 頂層目錄中。請注意，來源區域的頂層目錄「不一定」與存放區根目錄相同，因此 fuchsia.git 中的 tests/conformance 目錄不一定位於存放區根目錄。在其他以 Fuchsia 代管 SDK 為基礎的存放區中代管的 FHCP 測試，必須位於存放區頂層來源區域的 tests/conformance 目錄下，對應相關驅動程式庫區域 (例如 drivers/wlan.git,
drivers/audio.git)。
共用代碼
Fuchsia 機構支援多種在存放區之間共用程式碼的方法。
透過 Fuchsia SDK 分享
Fuchsia 託管存放區之間的主要程式碼共用機制是 Fuchsia SDK。Fuchsia SDK 用於開發在 Fuchsia 產品上執行的軟體。目前，Fuchsia 機構開發的 SDK 部分 (例如模擬器除外) 僅以 fuchsia.git 開發，但這可能會隨時間而有所不同。
Fuchsia SDK 由多個軟體構件 (或稱「元素」) 組成。RFC-0165 說明瞭多個 SDK 類別，每個元素都會指派其中一個類別。這些類別大致說明我們認為各項構件的穩定程度，以及適合使用的位置。其中有三個類別與本 RFC 相關：
internal：支援在 Fuchsia 平台來源樹狀結構中使用；partner：僅供特定合作夥伴使用；public：供一般大眾使用。
Fuchsia 開發人員可能熟悉 IDK，目前 IDK 包含一組合作夥伴 SDK 元素。
由於與平台相近，我們主要預期 Fuchsia 託管的 SDK 型存放區會使用合作夥伴和內部類別 SDK 元素。他們使用合作夥伴或內部服務，取決於用途：
Fuchsia 託管驅動程式應使用合作夥伴類別 SDK 元素開發，這些元素會從
fuchsia.git交付。例如，這包括 IDK 中的所有內容。SDK 的下游消費者 Fuchsia 託管元件應使用可從
fuchsia.git交付的合作夥伴類別 SDK 元素開發。實作合作夥伴類別 SDK 介面的 Fuchsia 代管元件，可能會使用內部 SDK 元素。
如果開發人員需要分享平台 API 或 ABI，請使用 Fuchsia SDK。具體來說，FIDL 定義是平台的介面，應透過 SDK 共用。如果開發人員認為以其他方式分享 FIDL 定義有優勢，應諮詢 Fuchsia API Council。
透過 Git 子模組分享
透過 Git 子模組共用程式碼是 fuchsia.git 的常見模式。Git 子模組是另一個專案中使用的 Git 專案。本節中的建議適用於 jiri 工具管理的存放區和 Git 子模組。
在許多情況下，不適合使用 SDK 分享程式碼。我們不希望透過 SDK 重新發布大多數第三方程式碼，因為這樣一來，我們 (而非第三方) 就必須為所有 SDK 使用者支援該程式碼。我們也有專供 Fuchsia 團隊使用的程式庫，例如 fbl。這些程式庫可能包含在內部 SDK 中，但使用合作夥伴 SDK 的 Fuchsia 團隊也可能接受使用這些程式庫。
此外，還有許多工具用於提升工程生產力，但專屬於 Fuchsia 的基礎架構和程式碼標準，例如程式碼格式化工具，以及查詢 Gerrit 的各種 fx 工具。
如要共用不應納入合作夥伴 SDK 的程式碼，可以將程式碼遷移至 Git 子模組，並在需要該程式碼的存放區之間共用。API 委員會和 RFC 程序會仲裁合作夥伴 SDK 中可納入的內容。
我們可能會使用這項機制，在 Fuchsia 機構開發人員之間分享目前儲存在 fuchsia.git 中的程式碼，但不想將程式碼放入 SDK，例如 fbl 或 boringssl 程式庫。
透過二進位檔分享
部分工具可能會透過二進位檔共用。舉例來說，我們使用 CIPD 製作工具鍊副本，提供給 fuchsia.git 開發人員。我們會繼續進行這項做法。最佳做法與上述 Git 子模組的最佳做法相同：建議開發人員使用適用於存放區的最新工具。
隨時取得最新資訊
Fuchsia 託管存放區必須保持在最新狀態，才能使用最新發布的軟體。
所有存放區都必須使用自動捲動器，以每天 (或更快的) 頻率更新依附元件。
如 RFC-0148 所述，每個專案應嘗試以快速的節奏發布及推出自己的內容。該 RFC 並未定義快速節奏，但建議理想狀態是新依附元件在發布後幾小時內推出。我們將快速發布的解讀留給存放區擁有者，但須注意以下事項。
所有存放區必須使用相容性窗口內的 SDK。 SDK 的相容性窗口是指以該 SDK 建構的程式碼，可與從主幹建構的 Fuchsia 產品搭配運作的時間長度。
如果存放區正在積極開發，且使用的 SDK 正在積極變更，以利支援該存放區中的用途，則應每天更新 SDK (並視解決不相容問題、基礎架構中斷和其他合理困難所需的時間進行調整)。
Fuchsia 機構將建立程序，在所有 Fuchsia 代管的存放區中執行更新 / LSC。每個存放區擁有者都必須提供聯絡窗口，以便快速回應緊急更新要求 (例如安全性問題、工具鍊更新修正等)。開發人員進行大規模變更時，可透過這個程序追蹤變更記錄。
所有存放區擁有者必須及時回應更新要求，確保安全或相容性。
多存放區開發
雖然所有簽入的程式碼都必須使用上述其中一種機制共用，但我們預期開發人員會有需要同時變更多個存放區中程式碼的使用案例。舉例來說，開發人員可能需要在 fuchsia.git 中開發新的 FIDL API，供 SDK 型工作流程中的驅動程式庫使用，並同時處理兩者的程式碼。
Fuchsia 團隊有讓多存放區工作流程正常運作的經驗。大部分的違規行為都屬於下列其中一類：
開發人員在
fuchsia.git中變更 SDK，然後匯出至其他 (目的地) 存放區使用。開發人員在一個來源存放區中處理元件時，需要將該元件發布至另一個 (目的地) 來源存放區代管的套件存放區。
在一個來源存放區中開發元件的開發人員，需要讓該元件可在另一個 (目的地) 來源存放區中用於系統組裝。
Fuchsia 團隊將開發相關工具，方便支援這些工作流程。
建構系統
Fuchsia 代管存放區必須使用 Bazel 建構系統。Fuchsia 對於新存放區採用 Bazel 的承諾，已在 RFC-0095 和 RFC-0139 中詳細說明，因此在此不需重述。
產品整合
由於我們支援的產品建構版本數量有限，目前不會要求產品使用專屬的產品整合存放區。Workstation 產品將繼續在 workstation.git 中執行組裝作業 (2023 年第 3 季注意事項：這項在 workstation.git 中執行組裝作業的計畫已遭 RFC-0220 淘汰)。
實作
這份 RFC 提供專案應如何配置及管理存放區的高階指南，但刻意省略實作細節。每個專案都可能以多種方式遵循指南，我們不想規定太多細節，以免造成人為限制。以 Fuchsia 為主機的 SDK 式專案才剛起步，因此我們在此規劃的任何內容，都可能隨著專案發展而過時。
效能
我們認為多個存放區的存在不會對效能造成重大影響。
目前，由於 fuchsia.git 中的所有程式碼都是從頭建構，且具有相同的依附元件和工具鍊設定，因此不同元件之間的共用程式碼完全相同。Fuchsia 的檔案系統會使用這項功能重複使用二進位檔，藉此節省目標裝置的空間。在多個存放區之間分割程式碼，會導致工具鍊和依附元件之間出現版本偏差，可能導致將相同二進位的不同版本部署至裝置，浪費空間。為避免發生這種情況，請盡量在所有存放區中維持相同的 SDK 和工具鍊 (請參閱上方的「保持最新狀態」一節)。
人體工學
如動機一節所述，我們相信 Bazel 和 SDK 的使用率提高後，驅動程式庫和元件開發人員的開發週期將會加快。
回溯相容性
如果存放區的共用程式碼過時，向後不相容的機率就會增加。因此，我們在「保持最新狀態」一節中提供相關建議。
安全性考量
我們認為 Fuchsia 託管存放區不會造成安全風險。
隱私權注意事項
我們認為 Fuchsia 託管存放區不會造成隱私權疑慮。
測試
我們認為不需要進行大量的新測試。無論來源位置為何，Fuchsia 基礎架構仍會執行所有相關測試。
說明文件
我們會製作操作指南和參考資料，協助您建立新存放區。我們也會建立可輕鬆複製的範例存放區 (這些存放區已存在，但程度不一)。
缺點、替代方案和未知事項
我們會在 Fuchsia 主機代管的 SDK 型存放區進行重大開發作業前，先公布這項 RFC。這裡的許多標準都是根據經驗的最佳猜測，可能無法滿足我們的需求。隨著我們對這些工作流程的經驗越來越豐富，以及鼓勵在 fuchsia.git 以外開發更多程式碼，我們可能會重新審查本文件中的指引。