Sdk: Please rename @Provisional to @Experimental

[matanlurey]

As of the latest dev release, we've added an @Provisional annotation
(https://github.com/dart-lang/sdk/blob/master/CHANGELOG.md)

Please consider undoing this ASAP, or at least before we release a stable Dart2 SDK.

There is already an @experimental in package:meta:
https://github.com/dart-lang/sdk/blob/7e78f0a95275d69230b156f03aacf0461e09770c/pkg/meta/lib/meta.dart#L239-L241

There is already an @Experimental in dart:html.

It would be nice to just combine these three into a single annotation available in dart:core.

[matanlurey]

_and_ we would be able to close https://github.com/dart-lang/sdk/issues/27124.

[leonsenft]

Experimental is much clearer than provisional. When I saw this come up in the change log, I had to go read the documentation to see what it was for, whereas experimental would have been self-explanatory.

[lrhn]

While I'm not too hung up on the name, the actual use-case we added this annotation for is indeed provisional (intended to be temporary and changed or removed later, a stop-gap measure until a proper solution can be made), not experimental (intended as a test, might become permanent).

Maybe the distinction isn't really worth two annotations (and maybe the annotation should be provisional too, or not be there at all - I'm leaning towards the latter. +@zanderso).

[matanlurey]

My understanding is @zanderso (very fairly) didn't want to spend the time updating dart:html in order to land, so this was chosen. I don't see a real difference in "intended to be temporary" and "intended as a test" and I don't think most folks consider _experimental_ to mean "intended as a test" in any case.

Let me know, I'm happy to help out when we decide to act.

[zanderso]

Based on the comments on the Experimental annotation in dart:html, it was my understanding that "experimental" has a specific technical meaning w.r.t. the W3C standardization process. It's possible that I misunderstood the comment there, but if I didn't, then I think it might make sense to leave Experimental where it is. If I did misunderstand the comment there, then we should probably move experimental to dart:core and re-export it from dart:html, which I think (?) won't be a breaking change.

[matanlurey]

@zanderso:

Based on the comments on the Experimental annotation in dart:html, it was my understanding that "experimental" has a specific technical meaning w.r.t. the W3C standardization process.

Even if that is the case (maybe @terrylucas can weigh in), we can always call this W3CExperimental, but I imagine it's totally fine to go with your intuition, which is just re-exporting dart:core -> dart:html. We aren't tied to Blink anymore, in any case.

[lrhn]

Do we actually need the annotation in the SDK?
Since annotations have no language meaning, and are entirely based on tools to give them a meaning, I really prefer to have annotations in package:meta where they are independent of SDK development.
The only problem with that is that it means we can't use those annotations in the SDK, which is why we have deprecated in dart:core.

An "Experimental" annotation in the SDK seems unnecessary since we are not planning to have a lot of experimental features in release versions of the SDK. If we have a feature and do not want people to use it accidentally, we can mark it deprecated (because it is, usage is deprecated).

So, I guess my preference is to remove the new annotation completely, and if needed, mark the feature as deprecated. Don't add a public annotation to the SDK for one use-case.

[matanlurey]

An "Experimental" annotation in the SDK seems unnecessary since we are not planning to have a lot of experimental features in release versions of the SDK.

Obviously not _totally_ true, for example the recent dart:cli feature is clearly "experimental" :). It's also possible that future Dart4Web SDK libraries might take more advantage of this annotation.

There is a little crazier of an idea, you could put it in dart:_annotations, and allow package:meta to export it, but still use it in dart:cli (and others). I think you follow this plan for some other things in the SDK, yes?

[matanlurey]

Can I help with this? Would love to see this happen and not get forgotten.

@lrhn

[lrhn]

The dart:cli feature is also not very "core". It's a "standalone VM"-only library, not something that everybody needs to know about.

I can accept one of two solutions in the core platform libraries:

• No annotation.
• A public annotation.

I don't want a "private but subtly leaked" annotation. Do or do not!

I'm leaning mostly towards "no annotation". We have very few annotations in the core libraries (two apart from this one, and I would actually prefer to only have @deprecated). From the language's point of view, annotations have no effect, and you must be able to use the language without them.
So, they are just about sending hints to users and tools. That's why @deprecated is allowed - it really has no effect apart from optionally causing a warning. An @experimental annotation is really the same, but then we run into the issue of having experimental features at all without a flag. Any feature we add, experimental or not, might be used by someone who will be annoyed when it's removed again, so we really shouldn't have them.

And, honestly, maybe we should just add "WARNING: Some text" to the documentation and make the tools report that pattern as a warning. I don't personally buy into the idea that everything must be annotations. Annotations are real values, they require available types and constructors to create. When you need the value at run-time, or when it makes sense to parameterize with structured values, then that's great, but a warning shouldn't need that.

[zanderso]

@lrhn My gut feeling is that it would be good to have this sort of guidance written up in a policy doc for the core libraries rather than buried in a github issue. Do we already have a doc somewhere like that?

@bwilkerson Is there any prior art for the analyzer parsing/understanding comments on functions, etc.?

We can also short circuit some of this and remove @provisional/@experimental without answering deeper policy questions if there's some indication that waitFor() has proved to be useful for something. /cc @nex3 @jakemac53

[bwilkerson]

Is there any prior art for the analyzer parsing/understanding comments on functions, etc.?

Yes. We recognize comments of the form // ignore: errorCode for the purpose of suppressing errors. I generally prefer to only use comments when (as in the ignore case) they need to be allowed in places where annotations are not allowed (such as on statements). It's much harder to document special comments which makes it harder for our tooling to be consistent and harder for users to discover the functionality. So I'd prefer a comment-based solution to be a last resort.

[nex3]

We can also short circuit some of this and remove @provisional/@experimental without answering deeper policy questions if there's some indication that waitFor() has proved to be useful for something.

I haven't had a chance to dive in yet--I'm not ready to tie Dart Sass to 2.0.0 dev versions yet.

[zanderso]

@nex3 I think the requirement that needs to be met to keep waitFor and remove the @provisional annotation is a bit weaker than having a Sass release depending on it. I think the question is more something like, "Have you written some code with it, and is there a good chance it will help your use case?"

[nex3]

Okay, I've run some local tests and it looks like waitFor() will definitely help make it possible to use Sass's synchronous path even with asynchronous callbacks :+1:.

[jakemac53]

cc @nshahan it would be interesting to see how this could simplify/speed up the sass_builder, we shouldn't need to set up a temp directory any more and shouldn't need to pre-parse imports either.

We could work up a prototype without any work in sass itself I believe?

[zanderso]

Cool. I am okay with removing @provisional, then. I think @matanlurey volunteered to do it ;-)

[matanlurey]

Definitely ... of course if you really really want to ...

[matanlurey]

Is it too late to do this for Dart2? @leafpetersen

[leafpetersen]

I don't know - is this used anywhere outside of our control?

[matanlurey]

Not that I am aware of. I did some searches

On Tue, Jun 5, 2018, 11:24 AM Leaf Petersen [e-mail]
wrote:

I don't know - is this used anywhere outside of our control?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/dart-lang/sdk/issues/31949#issuecomment-394811159,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAKQ7spn6jhsIlosBituLSJ3TKDUhfVOks5t5sxlgaJpZM4RlEAV
.

[leafpetersen]

Yeah, doesn't seem to have escaped much from what I can see. If you still want to do this, I say go ahead.

[matanlurey]

I forgot about this. I am hoping if I can convince @srawlins or someone else to send you a CL you'll still accept removing this.

[lrhn]

Definitely. No need to wait for a CL, though, I can do that quickly enough myself. How about: https://dart-review.googlesource.com/c/sdk/+/65081
(Well, "quickly enough" considering I got side-tracked updating the rest of the file)

[matanlurey]

So, we missed this for Dart 2, which is unfortunate.

@lrhn Can you land a @Deprecated(...) so we can at least remove it in Dart 3?

[lrhn]

Already on it: https://dart-review.googlesource.com/c/sdk/+/69462

(And I now kick myself for "updating the rest of the file" because that was why it didn't land. Do. one. thing. at. a. time!)