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

[Pascal]

+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:

Belated correction: here's a potential precedent:

https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.fonts.experimental/BUILD.gn

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]

+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:

Belated correction: here's a potential precedent:

https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.fonts.experimental/BUILD.gn

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]

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

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/fidl-dev/CAHKqeVHSDdWksNjbja7mK0WD3o958CXhKTiB0CgytUURA4Gn6Q%40mail.gmail.com.

[Jaeheon Yi]

+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.

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/fidl-dev/CAGEh6bg07q3hTxXj5Z-8EhHazbxw%2BB1GJWmnMd4%2BNPKL9QZ%2BDQ%40mail.gmail.com.

[Jaeheon Yi]

That guidance is here:

https://fuchsia.dev/fuchsia-src/concepts/source_code/layout?hl=en#overview

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]

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

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/fidl-dev/CADNd37ifDQ8pGXNgvo10%2Bbq%3DcKadWEL%3DBZRENG0yCX2pczj5%3DA%40mail.gmail.com.

[Filip Filmar]

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]

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]

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]

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]

It will from an API perspective

but ABI wise we also need 

https://fuchsia-review.googlesource.com/c/fuchsia/+/534921 or something like it

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.

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/fidl-dev/CADNd37ik%3DOG9M8uv9DEbaw%2BMvxjzD%3DirD_rCQxtimRvJ1CVX9w%40mail.gmail.com.

[Adam Barth]

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.

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/fidl-dev/CADNd37ik%3DOG9M8uv9DEbaw%2BMvxjzD%3DirD_rCQxtimRvJ1CVX9w%40mail.gmail.com.