Re: How to "graduate" part of an experimental FIDL API to a "partner" or "public" API?

35 views
Skip to first unread message

Pascal

unread,
Oct 7, 2021, 3:10:54 PM10/7/21
to Filip Filmar, graphi...@fuchsia.dev, fidl-dev, ui-inp...@fuchsia.dev
+graphi...@fuchsia.dev per Jaeheon 's email, joining the two threads

On Thu, Oct 7, 2021 at 3:06 PM Pascal <pasca...@google.com> wrote:
Which library are you looking to graduate, and which parts of this library will graduate?

Most likely the protocols which are graduating would go in fuchsia.thestablelibrary along with all transitive dependencies, which would then leave fuchsia.thestablelibrary.experimental having to import fuchsia.thestablelibrary in order to straddle both APIs. This will be source breaking, but the goal of an experimental API is to iterate in tree or allow for source breakages.

On Thu, Oct 7, 2021 at 3:00 PM 'Filip Filmar' via fidl-dev <fidl...@fuchsia.dev> wrote:

On Thu, Oct 7, 2021 at 11:55 AM Filip Filmar <fm...@google.com> wrote:
Hi fidlers!

Suppose I have an experimental FIDL library. (Marked as "experimental" in the SDK build rules.)

I'd like to "graduate" parts of the library to "partner" or "public" API, that part of the library is mature enough; while another part is still in development.

What would be the canonical way to do this for a FIDL library?  One way that comes to mind would be to have two FIDL libraries, an "experimental" and a "non-experimental" one, but I'm not finding precedent in //sdk/fidl.

Advice appreciated,
F


--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "fidl-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fidl-dev+u...@fuchsia.dev.
To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/fidl-dev/CAGEh6bgOihFt8ay4br1sZGfgA_u8cew98EMGa%2BDgndd-HHz9Gg%40mail.gmail.com.

Jaeheon Yi

unread,
Oct 7, 2021, 3:10:54 PM10/7/21
to Filip Filmar, fidl...@fuchsia.dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
+graphics-dev b/c the "Effects" API planned for Flatland is in the same general bucket. 



On Thu, Oct 7, 2021 at 12:00 PM 'Filip Filmar' via ui-input-dev <ui-inp...@fuchsia.dev> wrote:

On Thu, Oct 7, 2021 at 11:55 AM Filip Filmar <fm...@google.com> wrote:
Hi fidlers!

Suppose I have an experimental FIDL library. (Marked as "experimental" in the SDK build rules.)

I'd like to "graduate" parts of the library to "partner" or "public" API, that part of the library is mature enough; while another part is still in development.

What would be the canonical way to do this for a FIDL library?  One way that comes to mind would be to have two FIDL libraries, an "experimental" and a "non-experimental" one, but I'm not finding precedent in //sdk/fidl.

Advice appreciated,
F


--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "ui-input-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ui-input-dev...@fuchsia.dev.
To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/ui-input-dev/CAGEh6bgOihFt8ay4br1sZGfgA_u8cew98EMGa%2BDgndd-HHz9Gg%40mail.gmail.com.

Jaeheon Yi

unread,
Oct 7, 2021, 3:12:24 PM10/7/21
to Pascal, Filip Filmar, graphi...@fuchsia.dev, fidl-dev, ui-inp...@fuchsia.dev
Any particular advice on defining new data types in experimental libraries? I found that it's often nice to define new data types for each new protocol, but curious what others think, esp in an experimental context.

Jaeheon

Jaeheon Yi

unread,
Oct 7, 2021, 3:15:09 PM10/7/21
to Filip Filmar, Pascal, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
+graph...@fuchsia.dev for thread inclusion

On Thu, Oct 7, 2021 at 12:14 PM 'Filip Filmar' via fidl-dev <fidl...@fuchsia.dev> wrote:
On Thu, Oct 7, 2021 at 12:06 PM Pascal <pasca...@google.com> wrote:
Which library are you looking to graduate, and which parts of this library will graduate?

Only the enum fuchsia.input.keymap.Id would be graduating.
 
Most likely the protocols which are graduating would go in fuchsia.thestablelibrary along with all transitive dependencies, which would then leave fuchsia.thestablelibrary.experimental having to import fuchsia.thestablelibrary in order to straddle both APIs. This will be source breaking, but the goal of an experimental API is to iterate in tree or allow for source breakages.

SGTM.  This suggests to me that I'd need to create `fuchsia.input.keymap`.  And yes, the `....experimental` is fully contained in-tree.

F

--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "fidl-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fidl-dev+u...@fuchsia.dev.

Jaeheon Yi

unread,
Oct 7, 2021, 3:23:12 PM10/7/21
to Filip Filmar, Pascal, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev

On Thu, Oct 7, 2021 at 12:19 PM Filip Filmar <fm...@google.com> wrote:
On Thu, Oct 7, 2021 at 12:15 PM Jaeheon Yi <jae...@google.com> wrote:
+graph...@fuchsia.dev for thread inclusion

Thanks for the reminder!

Also, worth noting, it seems that we could technically have "experimental" or "internal" libraries live somewhere other than `//sdk/fidl`. 

But IIRC (not sure where I got this idea, correct if it's wrong) we specifically decided to not do that, but rather put all the FIDL API definitions in `//sdk/fidl`.

F

Jeremy Manson

unread,
Oct 7, 2021, 3:43:39 PM10/7/21
to Jaeheon Yi, Filip Filmar, Pascal, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
A lot of experimental features are doubtless going to take the form of new methods in stable protocols and the like, for which having them in a separate library will be a nuisance.  I idly wonder if it is worth extending RFC-0083 type features with a feature that allows some sort of indicator that an annotated element is experimental.  It could then be stripped prior to inclusion in a shipped SDK.

Jeremy

Filip Filmar

unread,
Oct 7, 2021, 3:43:48 PM10/7/21
to Jaeheon Yi, Pascal, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
On Thu, Oct 7, 2021 at 12:15 PM Jaeheon Yi <jae...@google.com> wrote:
+graph...@fuchsia.dev for thread inclusion

Thanks for the reminder!

Also, worth noting, it seems that we could technically have "experimental" or "internal" libraries live somewhere other than `//sdk/fidl`. 

But IIRC (not sure where I got this idea, correct if it's wrong) we specifically decided to not do that, but rather put all the FIDL API definitions in `//sdk/fidl`.

F

Filip Filmar

unread,
Oct 7, 2021, 3:46:04 PM10/7/21
to Jeremy Manson, Jaeheon Yi, Pascal, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
On Thu, Oct 7, 2021 at 12:30 PM Jeremy Manson <jeremy...@google.com> wrote:
A lot of experimental features are doubtless going to take the form of new methods in stable protocols and the like, for which having them in a separate library will be a nuisance.  I idly wonder if it is worth extending RFC-0083 type features with a feature that allows some sort of indicator that an annotated element is experimental.  It could then be stripped prior to inclusion in a shipped SDK.

It seems to me that this feature could fall naturally out of FIDL versioning, which is in development AFAIK.  Adding something like `@version(since="infinity")` (or whatever the appropriate annotation would be) could make an API element permanently invisible to the SDK.

F

Pascal

unread,
Oct 7, 2021, 3:49:52 PM10/7/21
to Filip Filmar, Jeremy Manson, Jaeheon Yi, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
Technically feasible to do (adding a lifecycle event that is before since).

One worry would be the entanglement of development features with non development features. The compiler would help enforce strict layering, but still might get more complicated than simply creating another library and playing with it. I would lean towards creating a green field library, separate from the rest, iterate there, then once stable look to integrate back into the main one. The downside is some sed work to replace names, but that is easily guided and checked by tools.

Jaeheon Yi

unread,
Oct 7, 2021, 5:23:04 PM10/7/21
to Pascal, Filip Filmar, Jeremy Manson, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
If new methods belong naturally in a stable protocol after graduating out of an experimental protocol, it seems manageable when paired with evolution-friendly patterns like @transitional and hanging-get. 

Pascal

unread,
Oct 7, 2021, 8:02:34 PM10/7/21
to Adam Barth, Filip Filmar, Jaeheon Yi, Jeremy Manson, fidl-dev, graphi...@fuchsia.dev, ui-inp...@fuchsia.dev
It will from an API perspective

but ABI wise we also need 

On Thu, Oct 7, 2021 at 7:55 PM Adam Barth <aba...@google.com> wrote:
See https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0083_fidl_versioning?hl=en#purpose_of_head , which I think will address your use case (once implemented and deployed).

Adam

--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "fidl-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fidl-dev+u...@fuchsia.dev.

Adam Barth

unread,
Oct 11, 2021, 11:18:38 AM10/11/21
to Jaeheon Yi, Pascal, Filip Filmar, Jeremy Manson, fidl-dev, ui-inp...@fuchsia.dev, graphi...@fuchsia.dev
See https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0083_fidl_versioning?hl=en#purpose_of_head , which I think will address your use case (once implemented and deployed).

Adam


--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "fidl-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fidl-dev+u...@fuchsia.dev.
Reply all
Reply to author
Forward
0 new messages