RFC-0231：FIDL 版本管理取代語法

RFC-0231：FIDL 版本管理語法
狀態已接受
領域
  • FIDL
說明

將 replace=N 引數新增至 @available 屬性
問題
  • 135676
毛皮變化
  • 922341
作者
審查人員
提交日期 (年-月-日)2023-09-26
審查日期 (年-月-日)2023 年 10 月 24 日

編輯此 RFC

編輯 RFC 中繼資料

摘要

變更 FIDL 的 @available 屬性，以便支援 replaced 引數。是 例如 removed，但會驗證替換品是否為 added 版本。

背景

RFC-0083：FIDL 版本管理引進了 @available 屬性 FIDL API 的版本管理該設計的規定之一是，允許所有版本 可能的變更。換句話說，應可表示「v1.fidl」 轉換至單一 versioned.fidl 中任意不同的 v2.fidl 檔案。這個設計非常滿意，因為它允許多個元素 請使用相同名稱，只要版本範圍不會重疊。

舉例來說，請考慮在以下位置為通訊協定 P 新增 @discoverable 屬性： 第 5 版。我們無法使用 @available 直接表示這個屬性，因為屬性 無法放置於其他屬性上不過，我們可以改為執行以下動作：

@available(added=1, removed=5)
protocol P {};

@available(added=5)
@discoverable
protocol P {};

如果在相同版本上移除元素再重新加入，這項技巧是 這種做法稱為「交換」。

提振精神

一般生命週期的新增、淘汰和移除 API 語法如下 符合直覺另一方面，交換模式則不會。這很合理 顧名思義，這個隱藏功能需要說明。在此例中， 以上，那麼建議您考慮removed=5 通訊協定推出第 5 版後，尤其是在對應的 added=5 未推出時 位於原始碼的相鄰點

區分拆卸與拆除物 也能避免使用 舊版功能，並替換為更通用的解決方案。這是 (提案：RFC-0232：適用於多個 API 級別的 FIDL 繫結)。

相關人員

講師：abarth@google.com

審查人員：hjfreyer@google.com、ianloic@google.com、ddorwin@google.com

諮詢者：Wez@google.com、sethladd@google.com、wilkinsonclay@google.com

社交：我與 FIDL 團隊和平台討論了這個想法 在寫入 RFC 之前的版本管理工作群組。

設計

  • 引入名為 replaced 的新 @available 引數。它的行為與 removed，但其驗證方式不同，如下所述。可以 ，在 library 宣告以外的任何元素上，而不是 removed。

  • 當元素標示為 removed=N 時，請確認其中「不」另一個元素 名稱相同的元素標示為 added=N。

  • 當元素標示為 replaced=N 時，驗證該元素是否「IS」另一個 名稱相同的元素標示為 added=N。

  • 這項驗證僅適用於直接標示為 removed 或 replaced，而非繼承引數的子元素。

範例

從新增 @discoverable 的「背景」區段範例 以及第 5 版的通訊協定在新設計中看起來會像這樣：

@available(added=1, replaced=5)
protocol P {};

@available(added=5)
@discoverable
protocol P {};

再舉一個例子，請考慮將包含成員的結構體替換為 匿名類型：

@available(added=1, replaced=2)
struct Foo {
    bar @generated_name("Bar") table {};
};

@available(added=2)
struct Foo {
    baz string;
};

由於第一個 Foo 標示為 replaced=2，fidlc 會驗證其是否存在 另一個 Foo 標記為 added=2。但「不會」執行類似的操作 子項元素 bar 和匿名類型 Bar 驗證。

實作

  1. 實作 replaced 引數，包括其驗證。

  2. 將所有 FIDL 檔案改為使用 replaced，而非 removed (如適用)。

  3. 實作新的 removed 驗證。如果 (2) 遺漏任何項目，CQ 就會失敗。

成效

此提案不會影響成效。

人體工學

本提案直接支援相關做法，使切換模式更加符合人體工學 變得越來越像

回溯相容性

本提案不會影響回溯相容性。

安全性考量

此提案不會影響安全性。

隱私權注意事項

此提案對隱私權沒有任何影響。

測試

必須先更新下列檔案，才能測試新行為：

  • tools/fidl/fidlc/tests/availability_interleaving_tests.cc
  • tools/fidl/fidlc/tests/decomposition_tests.cc
  • tools/fidl/fidlc/tests/versioning_tests.cc
  • tools/fidl/fidlc/tests/versioning_types_tests.cc

說明文件

下列頁面必須更新成文件 replaced：

「贈品」一詞並轉換為「已取代」

fidldoc 工具目前在 JSON IR 上針對單一 API 級別進行操作，因此 而且一律不會看到 removed 引數，也不會看到 replaced (https://fxbug.dev/42084086).修正此問題後，您應將 fidldoc 更新為 清楚指出某個項目何時被取代，而不是直接移除。

缺點、替代方案和未知

替代做法：重新加入引數

本提案推出了 replaced 引數，可讓您清楚掌握 而非移除元素。這可避免發生問題。 因為這個 API 顯示 removed=5，而我們指定 6，因此不方便使用。」

我們也可以用同樣的方式導入 re_added 引數，指出元素是 而非首次新增會 以避免發生這類情況：「我以為『我認為自己還無法使用這個 API，因為上面寫著 added=6，我們指定 5。」

我拒絕這個替代方案的原因有幾個：

  • 我認為第一個情境比第二種情況更重要。

  • 「re_added」這個名稱不太理想，我想起來了。

  • 就算沒有這樣，我們還是能利用 fidldoc 推論元素是否 added。

既有藝術品和參考資料

在 2021 年開發 FIDL 版本時，我在 標題為「FIDL 版本管理：切換元素」的內部文件。

此提案與 FIDL 版本管理的設計非常相關， 對這個議題的看法