Marking Libgpiod v2 api as experimental #2323
Conversation
| @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Libgpiod.V2; | |||
| /// allows callers to retrieve information about each line, watch lines for state changes and make line requests. | |||
| /// </summary> | |||
| /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__chips.html"/> | |||
| [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] | |||
There was a problem hiding this comment.
Why do we have to add this attribute to internal classes? They're not part of the API.
There was a problem hiding this comment.
Good question, short answer is that this way we know if any stable API depends on any unstable API.
Long answer: when marking some of the new public APIs as experimental, the internal code we added in libgpiod started to throw warnings as we were calling experimental APIs. There are two ways of getting rid of those warnings, you either suppress them (either in the callsite or just add it to NoWarn so they are suppressed for the whole project) or you mark the caller also as Experimental, which would just bubble the warning one level up the callstack. I chose the latter as otherwise we wouldn't know if any stable public facing API depended on any nom stable public facing API, so I marked each of the classes that showed warnings Experimental all the way up till O reached public API, and only suppressed the warnings there. This way, it requires a conscious decision to depend on experimental stuff from non experimental stuff.
There was a problem hiding this comment.
For instance, I know that today, the only two existing public APIs that are stable which may depend on any of the new experimental codepaths are UnixDriver.Create and LibGpiod constructor, because those are the only two places where I am suppressing the warnings.
Without making the internal types experimental in order to bubble up errors on the static analysis, figuring this out would be a challenge, and may lead us to depend on experimental stuff in places where we shouldn't.
cc: @raffaeler @Ellerbach @pgrawehr @krwq
Relates to #2271
Microsoft Reviewers: Open in CodeFlow