Sdk: Add an @alpha annotation?

[trentgrover-wf]

It would be really useful to have an annotation that we could use to indicate that some classes, methods, etc are experimental (@alpha, @beta, @experimental, or similar).

Some of our Dart libraries are reasonably mature and we rely on semver to indicate to consumers when breaking changes occur. It's difficult to add experimental apis within a mature library while adhering to semver, so it would be awesome if we could annotate experimental code to indicate that the normal semver rules aren't being respected for this code (breaking changes may occur without a major semver release).

Is there a way to add an annotation for this to the meta package?

[zoechi]

You can just create your own package with these annotations.
The annotations by themselves don't do much anyway.
Interesting would be what you want to get from these annotations.
Analyzer support? In what way?

https://github.com/dart-lang/sdk/blob/0c1e85ebadaa0680d4ff30acc1f3ac823c53756e/sdk/lib/html/html_common/metadata.dart contains similar annotations. Unifying them in a package like meta would IMHO make sense.

[beta]

I'm wondering if @alpha is receiving as many tons of unintended mentions as I do every day :D.

[floitschG]

Assigned to 'area-analyzer' since the analyzer team seems to maintain the meta package.

[bwilkerson]

We generally add annotations to the meta package only when there is (or reasonably could be) tooling support associated with the annotation. I'm not sure what tooling support this would enable, so I'm not inclined to add it.

[trentgrover-wf]

The most direct parallel for what we'd like to do with this sort of annotation is @deprecated. Similarly, we'd like to call attention to the use of experimental code in the analysis process so that it stays front of mind for devs and we can guard against it in our CI process if desired.

At the moment, we're bastardizing @deprecated for this purpose, but it would be better if we could differentiate between code that is 'flagged' because it's deprecated vs because it's using an experimental api.

[zoechi]

So a linter rule similar to what @deprecated does that can be enabled using .analysis_options

[bwilkerson]

I suspect that this annotation wants to be a little different than deprecated.

The deprecation hint is produced for any use of a deprecated member that occurs anywhere (either inside or outside the declaring library / package) unless it is inside a deprecated member.

My guess is that we'd want to allow references to such code (we've been calling it provisional) inside the same package, because you wouldn't have added it if you didn't intend to use it in order to gain experience with it. The question is, is that enough, or do you need to be able to reference it from other packages in order to experiment with it? Can we precisely define when a hint/lint should be produced?

[trentgrover-wf]

That sounds about right to me. For the 'provisional' tag:

• Don't hint for uses within the package it's declared in
• Do hint when anything provisional has been referenced by a consumer of the package

[matanlurey]

Bump:

I'd like to see @experimental in package:meta. Rationale:

• For projects using strict semver, removing any public API is a XX.##.## bump
• @experimental could be used to loosen that restriction, i.e. only a ##.XX.## bump

We are considering automated tools similar to Elm that actually check your pubspec.yaml version is updated if your public interface has changed, and if we have these tools we'd need @experimental in order to get around them.

The rationale for being here versus say, package:strict_semver, is that the analyzer/IDE could give warnings to users that are using these APIs - perhaps also configurable in .analysis_options:

analyzer:
  warn_experimental_features: <true|false>

That way teams that don't have a huge migration/deprecation budget could avoid using these.

[trentgrover-wf]

any chance of this happening?

[matanlurey]

Ah, that's what it was called. Thanks @bwilkerson

[bwilkerson]

Yes, there appears to be increasing demand for it, so I think it's time. I'll start with defining the annotation, then we can hammer out the specific of analyzer support.

[matanlurey]

Thanks Brian! Let me know if you'd like to chat re: specifics after this lands.

[bwilkerson]

This adds the annotation: https://codereview.chromium.org/2789843003/. Analyzer support will follow, but not immediately.

[trentgrover-wf]

any update on analyzer support for this annotation?

[bwilkerson]

No, sorry, there hasn't been any work done on this yet.

[matanlurey]

What would the analyzer support do?

[bwilkerson]

As discussed earlier in this issue, produce a hint if any code outside the declaring package makes use of experimental APIs.

[natebosch]

Do we consider this complete since @experimental is implemented?