RFC-0216：Fuchsia 代管的存放區指南

RFC-0216：Fushisia 託管存放區指南
狀態已接受
領域
  • 開發人員
  • 管理事宜
  • 一般
說明

fuchsia.git 以外的 Fuchsia 代管程式碼開發指南
問題
更小鳥
作者
審查人員
提交日期 (年月分)2022-1-17
審查日期 (年-月-日)2023-04-20

編輯這個 RFC

編輯 RFC 中繼資料

摘要

隨著我們開始針對 Fuchsia 提供 Bazel 完整支援，且越來越多人將重點放在功能全面的 Fuchsia SDK，因此 fuchsia.git 中開發 Fuchsia 元件的優勢已大幅減少。這個 RFC 概述了在其他由 Fuchsia 託管的存放區中開發元件的規定和最佳做法。無法解決 fuchsia.git 外組合的需求。

提振精神

自 Fuchsia 專案開始以來，大部分的開發作業都是在 jiri 工具代管的單一環境中進行，透過協調多個原始碼存放區的開發作業，就像單一存放區一樣。如今，我們非正式將該環境稱為 fuchsia.git，因為 Fuchsia 的大部分開發作業是以該存放區為中心。

單一代管環境 (大多在單一存放區中) 有明顯的開發優勢。整個程式碼集可以快速更新程式碼，通常只需一次變更，這樣就減少了不同存放區中不同版本之間的協調工作。開發人員工具和第三方 / 程式庫程式碼的更新可集中管理，這代表整個機構都能共享升級和程式碼清理的優點。常見的程式碼標準可讓您不再需要使用程式碼樣式或目錄版面配置的引數。開發人員知道要搜尋任何指定程式碼的存放區。

然而，集中式存放區無法滿足所有 Fuchsia 開發人員的需求。Fuchsia 的存放區要求開發人員建構完整的系統映像檔和 SDK，以大幅影響開發人員的速度。如需要在 fuchsia.git 中建構系統映像檔和 SDK，這表示許多開發人員對於建構體驗的體驗大不相同。

更重要的是，Fushisia 團隊為未在 fuchsia.git 中工作的開發人員建立抽象化機制，但我們通常不會自己使用這類功能。如果開發人員在 fuchsia.git 中預期需要標準 Fuchsia 工作流程，但會使用 fx 工具和各種指令碼，卻幾乎不滿，這與我們與 SDK 型開發人員分享的內容完全不同，就會產生問題。這也會讓以 fuchsia.git 為基礎的開發人員更難理解 SDK 的開發人員，因為他們不會使用相同的工作流程，因此不會有相同的獎勵，讓這些工作流程更臻完善。

Fuchsia Build 團隊正在努力解決以 fuchsia.git 為基礎的工作流程和以 SDK 為基礎的工作流程之間的部分差異，但會一直存在一些落差，原因就是其他存放區使用以 SDK 為基礎的工作流程的開發人員無需將這些工作流程建構 SDK 或系統映像檔。

我們不希望所有開發人員在不久後將程式碼移至以 SDK 為基礎的工作流程。2023 年，該團隊將全力支援將驅動程式從 fuchsia.git 中移出。如為其他專案，則可選擇是否要移出 fuchsia.git。在短期內，我們預計大部分可以完全在以 SDK 為基礎的 API 上建構的元件，都可以從 fuchsia.git 中遷移。

為了提升開發人員在不為 SDK 提供資源的專案工作效率，以及提升 Fuchsia 團隊中 SDK 開發人員的同理心，Fushisia 社群希望鼓勵開發人員在 fuchsia.git 以外使用以 SDK 為基礎的工作流程。不過，我們並沒有明確的做法指南。我們根據過去幾年來 SDK 工作流程和 fuchsia.git 工作流程的經驗，提供了這項 RFC，以便您開始填補這些缺口。

相關人員

講師：

  • David Moore (davemoore@google.com)

審查者：

  • Adam Barth (abarth@google.com) - 美國聯邦選舉委員會
  • Chase Latta (chaselatta@google.com) - Bazel 支援
  • Nathan Mulcahey (nmulcahey@google.com) - EngProd
  • Suraj Malhotra (surajmalhotra@google.com) - 驅動程式

諮詢時間：

下列人員已進一步查看這個 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)
  • 雷納托曼吉尼迪亞斯
  • 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)

社會化：

這個 RFC 的短版由 EngProd、FHCP、驅動程式、工程顧問、Bazel SDK 整合和 DevRel 團隊與社群有關聯。

設計

以下提供一組指南，用於啟動及開發以 SDK 為基礎的 SDK 託管存放區。但這並未涵蓋所有情況。舉例來說，雖然我們針對如何持續更新 Fuchsia 託管存放區中的 SDK 制定了一些規範，但並未就此程序提供詳細的設計。

存放區命名

存放區名稱取決於存放區的內容。我們將本指南細分為驅動程式庫和非驅動程式庫存放區。

驅動程式

不屬於特定廠商的驅動程式程式碼應託管在由驅動程式庫區域命名的存放區 (例如驅動程式/audio.git、drivers/wlan.git)。例如鍵盤和滑鼠等一般驅動程式的程式碼。封閉原始碼也不應進入這些存放區。

我們深知這些區域的名稱會隨著時間改變。將存放區移至新的路徑可能並不容易。我們建議開發人員謹慎選擇區域名稱，並確保日後變更名稱時進行盡職調查。

特定廠商專屬的驅動程式程式碼應託管於驅動程式///。例如，drivers/wlan/intel/iwlwifi。團隊可靈活決定存放區邊界的位置 (例如 drivers/wlan/intel/iwlwifi 是否為獨立的存放區，或者是否位於 drivers/wlan 存放區)。我們可根據現有體驗提供了一些指引，我們相信未來將持續開發更多相關體驗：

  • 如果驅動程式庫需要封閉原始碼軟體才能建構，則建議將其放在與完全開放原始碼驅動程式的不同存放區中。

  • 如果多個驅動程式共用大量程式碼 (請見下方程式碼共用)，請將這些驅動程式與該程式碼存放在單一存放區中，即可避免在多個存放區中推出該程式碼的更新。在這種情況下，開發人員往往很難找出所有相關存放區、在當中建構軟體，並進行測試。對大多數程式碼而言，存放區越少，就越容易遵循程式庫、SDK 和工具鍊的最新更新。

  • 有時候，多個驅動程式會共用次要的程式碼，但在某些情況中，這些驅動程式會將其保存在獨立的存放區中。針對名稱重疊的存放區 (例如，如果 drivers/<area> 和 drivers/<area>/<vendor> 皆為存放區) 並不容易，而這項重疊可能會導致開發人員想在同一個目錄中檢查兩個存放區時，就產生意外衝突。建議您將通用程式碼放在名為 drivers/<area>/common 的存放區中，而不是名為 drivers/<area>。為避免程式碼遷移的成本，您可以在多個驅動程式需要之前，就先在常見區域開發程式碼。

  • 駕駛團隊可決定釋出驅動程式來取得穩定分支版本的認證。如果他們這麼做，比起多個分支版本，他們管理一個分支會更容易。Fuchsia 團隊正在為驅動程式庫認證開發最佳做法，這類做法可能是未來 RFC 的範疇。

非驅動程式庫元件

與驅動程式無關的元件原始碼可以託管於兩個位置。開發人員能享有彈性的選擇。

元件可能託管於贊助該元件 (例如 Experience.git) 的功能區域名稱的存放區中。我們建議功能區域外的開發人員不會引起開發人員興趣的元件使用，建議採用此做法。

元件可能託管於以專案命名的存放區中 (例如 workstation.git、cobalt.git)。我們建議功能地區以外的開發人員可能有興趣的大型專案和專案使用此選項。

與驅動程式庫程式碼一樣，共用來源基礎各有優缺點。本節所述的注意事項也適用於元件。

存放區版面配置

該程式碼的版面配置應與 Fuchsia 原始碼版面配置文件中的相同。必須更新原始碼版面配置文件，以反映 Bazel 建構系統的允許使用；例如允許 BUILD.bazel 而非 BUILD.gn 使用，且具有 WORKSPACE 檔案。

系統會提供基本範本存放區，開發人員可以複製這個存放區來建立新的存放區。我們可能有其他存放區含有驅動程式和元件專用的工具和版面配置，而在開發相關需求時，也會考慮產品整合。範本將包含 Fuchsia 存放區的必要基本概念。例如，目前包含 LICENSE 檔案、一個具有預先定義目標的 Bazel 建構檔案，讓基礎架構讀取這些內容，以便判斷要建構及測試哪些內容，以及列出至少兩位擁有者的頂層 OWNERS 檔案。

駕駛人須通過認證測試。這項認證計畫稱為 Fuchsia Hardware 認證計畫 (FHCP)。在 fuchsia.git 代管的 FHCP 測試應位於相關來源區域中名為 tests/conformance 的頂層目錄。請注意，來源區域的頂層目錄「不一定」與存放區根目錄相同，因此 fuchsia.git 中的 tests/conformance 目錄不一定要位於存放區根目錄中。如果 FHCP 測試託管在其他 Fuchsia 代管的 SDK 存放區中，則必須位於存放區頂層來源區域的 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，這種 ID 目前包含一組合作夥伴 SDK 元素。

由於這些程式庫與平台的距離近，我們主要預期由 Fuchsia 代管的 SDK 存放區使用合作夥伴和內部類別 SDK 元素。請根據合作夥伴的用途，選擇使用合作夥伴或內部服務：

  • Fuchsia 代管的驅動程式應使用透過 fuchsia.git 提供的合作夥伴類別 SDK 元素開發。這包括 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 的基礎架構和程式碼標準，例如程式碼格式程式和各種查詢語言的 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 團隊具備建立多存放區工作流程的經驗。這些 API 通常屬於以下其中一個類別：

  • 使用 fuchsia.git 的開發人員對 SDK 做出變更，然後匯出 SDK 並用於其他 (目的地) 存放區。

  • 在一個來源存放區中處理元件的開發人員，必須將該元件發布至另一個 (目的地) 來源存放區代管的套件存放區。

  • 在一個來源存放區處理元件的開發人員需要將該元件提供給另一個 (目的地) 來源存放區的系統組合。

Fuchsia 團隊將開發出能輕鬆支援這些工作流程的工具。

建構系統

Fuchsia 託管存放區必須使用 Bazel 建構系統。Fuchsia 對 Bazel 建立新存放區的承諾詳見 RFC-0095 和 RFC-0139，此處無需重複。

產品整合

由於我們支援的產品版本數量有限，目前我們不需要使用特別的產品整合存放區。工作站產品會繼續在 workstation.git 中執行組合 (2023Q3 附註：這個 workstation.git 中組合的計畫已由 RFC-0220 淘汰)。

實作

這份 RFC 提供高階指南，說明專案應如何安排及管理存放區，但重點在於實作詳細資料。每個專案可能會以多種方式遵循指南規範，而我們不希望提出過多具體說明以建立限制。採用 Fuchsia 託管的新 SDK 專案仍在開始，而此處列出的內容可能會隨著專案演進而過時。

效能

我們相信，擁有多個存放區會對效能造成重大影響。

目前，由於 fuchsia.git 中的所有程式碼都是以相同的依附元件和工具鍊設定建構，因此不同元件之間的共用程式碼的位元相同。Fuchsia 的檔案系統會使用這項功能簡化二進位檔，進而節省目標裝置空間。在多個存放區間分割程式碼會導致工具鍊與依附元件之間的版本偏差，進而導致將相同二進位檔的不同版本部署至裝置，因而造成空間消耗。可以設法避免這種情況發生，方法是嘗試讓所有存放區使用相同的 SDK 和工具鍊 (請參閱上方「保持最新狀態」一節)。

人體工學

如動機一節所述，我們認為 Bazel 的使用率增加，且 SDK 可加快驅動程式庫和元件開發人員的開發週期速度。

回溯相容性

存放區會導致共用程式碼過舊，因此回溯不相容的機率會增加。因此，我們會在「保持最新狀態」部分提供建議。

安全性考量

我們認為 Fuchsia 代管的存放區不會帶來安全性風險。

隱私權注意事項

我們不相信 Fuchsia 代管的存放區會產生隱私權疑慮。

測試

我們認為不需要進行大規模的全新測試，無論來源位置為何，Fuschia 基礎架構仍會執行所有相關測試。

說明文件

我們將建立使用指南和參考資料來啟動新的存放區。我們也會建立可輕鬆複製的範例存放區 (在某種程度內，已有這類存放區)。

缺點、替代項目和未知

在託管於 Fauchsia 的 SDK 存放區之前，我們正在積極推動這個 RFC。此處的許多標準都是基於經驗的最佳推測，可能不符合我們的需求。隨著這些工作流程累積更多經驗，我們日後可能會重新審閱本文件中的指南，同時也鼓勵在 fuchsia.git 以外的地方開發更多程式碼。