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

摘要

隨著 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) - 驅動程式

諮詢：

我們也諮詢了以下其他人員，針對此 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)

社會化：

我們已將這份 RFC 的簡短版本與 EngProd、FHCP、Drivers、Eng Council、Bazel SDK Integration 和 DevRel 團隊分享。

設計

以下是一系列指南，可協助您啟動及開發以 SDK 為基礎的 Fuchsia 代管存放區。但並非詳盡無遺。舉例來說，雖然我們已針對如何讓 Fuchsia 代管存放區中的 SDK 保持更新，提供一些規範，但並未詳細設計該程序。

存放區命名

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

驅動程式

不屬於特定供應商的驅動程式程式碼應放置於以驅動程式庫區域命名的存放區中 (例如 drivers/audio.git、drivers/wlan.git)。例如鍵盤和滑鼠等通用驅動程式的程式碼。封閉原始碼也不應放入這些存放區。

我們瞭解這些地區的名稱可能會隨著時間改變。將存放區移至新路徑可能會很困難。我們建議開發人員謹慎選擇所在地區的名稱，並確保日後變更名稱時能做好盡職調查。

特定供應商的驅動程式碼應放置於 drivers///。例如：drivers/wlan/intel/iwlwifi。團隊可以彈性決定存放區界線 (例如 drivers/wlan/intel/iwlwifi 是否為獨立存放區，或是否放入 drivers/wlan 存放區)。我們可以根據現有經驗提供一些指引，相信日後會有更多相關經驗：

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

• 如果多個驅動程式共用大量程式碼 (請參閱下方的程式碼共用)，請將這些驅動程式與程式碼一起保留在單一存放區，以免在多個存放區中為該程式碼推出更新時遇到困難。在這種情況下，開發人員經常很難找到所有相關的存放區，並在其中建構及測試軟體。對於大多數程式碼而言，存放區越少，就代表您需要花費的時間就越少，才能追蹤程式庫、SDK 和工具鍊的最新更新。

• 有時，多個驅動程式會共用實質程式碼，但情況會決定將這些程式碼保留在個別存放區。Gerrit 支援名稱重疊的存放區 (例如，如果 drivers/<area> 和 drivers/<area>/<vendor> 都是存放區) 會造成不便，而且當開發人員想要將兩個存放區都檢出至同一個目錄時，重疊的情況可能會造成意外衝突。建議您將常用程式碼放在名稱為 drivers/<area>/common 的存放區，而非 drivers/<area>。在多個驅動程式需要程式碼之前，可以先在常用區域中開發程式碼，以免產生程式碼遷移成本。

• 驅動程式團隊可能會決定將驅動程式發布至穩定分支，以便進行認證。這樣一來，他們可能會發現管理一個分支比管理多個分支更容易。Fuchsia 團隊正在開發驅動程式庫認證的最佳做法，這可能會是未來 RFC 的主題。

非驅動程式庫元件

與驅動程式無關的元件原始碼可能會託管在以下任一位置：開發人員可彈性選擇。

元件可能會託管在以贊助該元件的功能領域命名的存放區中 (例如 experiences.git)。建議將此做法用於功能領域以外的開發人員不太可能感興趣的元件。

元件可能會託管在以專案命名的存放區中 (例如 workstation.git、cobalt.git)。我們建議將此做法用於大型專案，以及可能吸引功能領域外開發人員的專案。

與驅動程式庫程式碼一樣，共用來源基礎也有優缺點。該部分所述的考量也適用於元件。

存放區版面配置

程式碼版面配置應與 Fuchsia 原始碼版面配置文件中的版面配置相同。您必須更新原始碼版面配置文件，以便反映可用的 Bazel 建構系統，也就是允許使用 BUILD.bazel 而非 BUILD.gn，以及使用 WORKSPACE 檔案。

開發人員可以複製基礎範本存放區，建立新的存放區。我們可能會有其他程式碼集，其中包含專門針對驅動程式和元件設計的工具和版面配置，如果我們需要整合產品，也會有相關程式碼集。範本會包含 Fuchsia 存放區所需的基本項目。目前的範例包括授權檔案、Bazel 建構檔案 (內含基礎架構可讀取的預先定義目標，以便瞭解要建構和測試的項目)，以及列出至少兩位擁有者的頂層 OWNERS 檔案。

駕駛人必須通過認證測試。這項認證計畫稱為 Fuchsia 硬體認證計畫 (FHCP)。在 fuchsia.git 中代管的 FHCP 測試，應位於相關來源區域中名為 tests/conformance 的頂層目錄。請注意，來源區域的頂層目錄不一定與存放區根目錄相同，因此 fuchsia.git 中的 tests/conformance 目錄不一定位於存放區根目錄。在其他 Fuchsia 代管的 SDK 相關存放區中代管的 FHCP 測試，必須位於相關驅動程式庫程式區域 (例如 tests/conformancedrivers/wlan.git、drivers/audio.git)。

共用程式碼

Fuchsia 組織支援在存放區之間共用程式碼的多種方法。

透過 Fuchsia SDK 分享

Fuchsia SDK 是 Fuchsia 代管存放區之間分享程式碼的主要機制。Fuchsia SDK 可用於開發在 Fuchsia 產品上執行的軟體。由 Fuchsia 團隊開發的 SDK 部分 (例如模擬器除外)，目前僅在 fuchsia.git 中開發，但這可能會隨時間而有所變動。

Fuchsia SDK 由多個軟體成果物或元素組成。RFC-0165 說明瞭幾個 SDK 類別；每個元素都會指派其中一個類別。這些類別大致說明我們認為每個構件有多穩定，以及這些構件適合用於何處。其中三個類別與本 RFC 相關：

• internal：可在 Fuchsia 平台來源樹狀結構中使用；
• partner：部分合作夥伴可使用；
• public：一般大眾可使用。

Fuchsia 開發人員可能熟悉 IDK，目前由一組合作夥伴 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 委員會。

透過 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.git 中的程式碼，這些程式碼我們希望在 Fuchsia 組織開發人員之間共用，但不想放入 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 建構系統。RFC-0095 和 RFC-0139 已詳細說明 Fuchsia 對 Bazel 的新存放區的承諾，因此在此處無須重複說明。

產品整合

由於我們支援的產品版本數量有限，因此目前不會要求產品提供專屬的產品整合存放區。工作站產品將繼續在 workstation.git 中執行組裝作業。(2023Q3 附註：RFC-0220 已淘汰在 workstation.git 中執行組裝作業的計畫)。

實作

本 RFC 提供高層級指南，說明專案應如何規劃及管理其存放區，但刻意不提及實作細節。每個專案都可能以多種方式遵循指南，我們不希望因為規定太多細節而造成人為限制。新的 Fuchsia 代管 SDK 專案仍在起步階段，因此隨著專案的演進，這裡的對應項目可能會失效。

成效

我們認為，多個存放區的存在不會對效能造成重大影響。

由於 fuchsia.git 中的所有程式碼都是從主程式建構，且具有相同的依附元件和工具鍊設定，因此不同元件之間的共用程式碼會位元為單位完全相同。Fuchsia 的檔案系統會使用這項功能來去除重複的二進位檔，進而節省目標裝置的空間。在多個存放區中分割程式碼會導致工具鍊和依附元件之間的版本偏差，可能導致相同二進位檔的不同版本部署至裝置，導致空間耗用量增加。您可以盡量在所有存放區中使用相同的 SDK 和工具鍊，以減輕這類問題的影響 (請參閱上方的「保持最新狀態」一節)。

人體工學

如動機一節所述，我們認為使用更多 Bazel 和 SDK 可縮短驅動程式庫和元件開發人員的開發週期。

回溯相容性

當存放區讓共用程式碼過時，向後相容性不相容的機率就會增加。因此，我們會在「保持最新狀態」一節中提供相關建議。

安全性考量

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

隱私權注意事項

我們認為 Fuchsia 代管的存放區不會造成隱私權疑慮。

測試

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

說明文件

我們會建立如何開始使用新存放區的指南和參考資料。我們也會建立可輕鬆複製的範例存放區 (這些存放區在某種程度上已經存在)。

缺點、替代方案和未知事項

我們會在 Fuchsia 代管的 SDK 存放區進行重大開發作業前，提前發布此 RFC。這裡的許多標準都是根據經驗做出的最佳推測，可能無法滿足我們的需求。隨著我們對這些工作流程的經驗越來越豐富，我們也鼓勵在 fuchsia.git 之外開發更多程式碼，因此很可能會重新審視本文件中的指南。