[dart:core] Adds @Provisional annotation

@Experimental is already defined in dart:html. Adding the same
annotation to dart:core breaks the build. Removing the annotation from
dart:html and adding it to dart:core is a breaking change, e.g.
if someone has said "import 'dart:html' show Experimental".

This annotation is for use in the upcoming dart:standalone with
the waitFor(Future f) function:

https://dart-review.googlesource.com/c/sdk/+/29449
Change-Id: Iea2f537a2ae89a6097c4284084a2a168e833bb04
Reviewed-on: https://dart-review.googlesource.com/30261
Commit-Queue: Zach Anderson <zra@google.com>
Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>

CHANGELOG.md

@@ -46,6 +46,7 @@
     `SECONDS_PER_DAY` to `secondsPerDay`,
     `MINUTES_PER_DAY` to `minutesPerDay`, and
     `ZERO` to `zero`.
+  * Added `Provisional` annotation to `dart:core`.
 
 * `dart:convert`
   * `Utf8Decoder` when compiled with dart2js uses the browser's `TextDecoder` in

sdk/lib/core/annotations.dart

@@ -72,15 +72,15 @@ class Deprecated {
   String toString() => "Deprecated feature. Will be removed $expires";
 }
 
-class _Override {
-  const _Override();
-}
-
 /**
  * Marks a feature as [Deprecated] until the next release.
  */
 const Deprecated deprecated = const Deprecated("next release");
 
+class _Override {
+  const _Override();
+}
+
 /**
  * The annotation `@override` marks an instance member as overriding a
  * superclass member with the same name.
@@ -108,6 +108,59 @@ const Deprecated deprecated = const Deprecated("next release");
  */
 const Object override = const _Override();
 
+/**
+ * The annotation `@Provisional('message')` marks a feature as provisional.
+ *
+ * An API is considered to be provisional if it is still going through the
+ * process of stabilizing and is subject to change or removal.
+ *
+ * The intent of the `@Provisional` annotation is to mark APIs that are still in
+ * development or that are added only tentatively. Adding the API allows users
+ * to experiment with using the APIs, which can provide valuable feedback. Such
+ * provisional APIs do not promise stability. They can be changed or removed
+ * without warning.
+ *
+ * The `@Provisional` annotation applies to:
+ * - library directives,
+ * - public top-level declarations, and
+ * - public members of public classes.
+ *
+ * Provisionality is transitive:
+ * - If a library is provisional, so is every member of it.
+ * - If a class is provisional, so is every member of it.
+ * - If a variable is provisional, so are its implicit getter and setter.
+ *
+ * Further, if a class is provisional, so are classes that extend, implement,
+ * and mix-in the class.
+ *
+ * A tool that processes Dart source code may report when:
+ * - the code imports a provisional library.
+ * - the code exports a provisional library, or any provisional member of
+ *   a non-provisional library.
+ * - the code refers statically to a provisional declaration.
+ * - the code dynamically uses a member of an object with a statically known
+ *   type, where the member is provisional on the static type of the object.
+ *
+ * If the provisional use is inside a library, class or method which is itself
+ * provisional, the tool should not bother the user about it.
+ * A provisional feature is expected to use other provisional features.
+ */
+class Provisional {
+  /**
+   * A brief message describing how or why the feature is provisional.
+   */
+  final String message;
+
+  const Provisional({String message})
+      : this.message = message ?? "Subject to change or removal.";
+}
+
+/**
+ * Marks a feature as provisional with the message "Subject to change or
+ * removal".
+ */
+const Provisional provisional = const Provisional();
+
 class _Proxy {
   const _Proxy();
 }