[tools] Update documentation about experimentalReleaseVersion in experiment flags.

Tweaking the documentation a tad to enforce the new process of:
1. Add an `experimentalReleaseVersion` when you make the flag and set it to the current latest version at the time of creation.
2. Bump the `experimentalReleaseVersion` when you make a relevant change in the allowlist that would allow those libs/packages to use the feature by default.

The chat thread context: https://chat.google.com/room/AAAA4GpVqbE/r2QigevCdQo/tP7lLb8I728?cls=10

Change-Id: I8ddad40e0ac82b6deaae9a6671bec4d47ea07fba
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/443636
Commit-Queue: Kallen Tu <[email protected]>
Reviewed-by: Nate Bosch <[email protected]>
Reviewed-by: Konstantin Shcheglov <[email protected]>

Author: kallentu

pkg/front_end/lib/src/api_prototype/experimental_flags_generated.dart

@@ -30,13 +30,14 @@ class ExperimentalFlag {
   final bool isExpired;
   final Version enabledVersion;
 
-  /// The minimum version that supports this feature.
+  /// The minimum version that enables the feature by default.
   ///
   /// If the feature is not enabled by default, this is the current language
   /// version.
   final Version experimentEnabledVersion;
 
-  /// The minimum version that supports this feature in allowed libraries.
+  /// The minimum version that allows this feature to be enabled with a flag and
+  /// enables the experiment in allowed libraries.
   ///
   /// Allowed libraries are specified in
   ///

pkg/front_end/tool/generate_experimental_flags.dart

@@ -278,16 +278,17 @@ class ExperimentalFlag {
   final bool isExpired;
   final Version enabledVersion;
 
-  /// The minimum version that supports this feature.
+  /// The minimum version that enables the feature by default.
   ///
   /// If the feature is not enabled by default, this is the current language
   /// version.
   final Version experimentEnabledVersion;
 
-  /// The minimum version that supports this feature in allowed libraries.
+  /// The minimum version that allows this feature to be enabled with a flag and
+  /// enables the experiment in allowed libraries.
   ///
   /// Allowed libraries are specified in
-  /// 
+  ///
   ///    sdk/lib/_internal/allowed_experiments.json
   final Version experimentReleasedVersion;
 

tools/experimental_features.yaml

@@ -51,13 +51,25 @@
 #    to disable this feature. For more on library language version override, see
 #    https://dart.dev/to/language-version-override
 #
-# 3. expired: (optional boolean)
+# 3. experimentalReleaseVersion: (optional #.#)
+#    The Dart SDK version (<major>.<minor>) in which the experiment can be used
+#    by enabling the experiment flag.
+#
+#    If this field is specified, then the experiment may be enabled in this
+#    version or later versions, by specifying the flag on the command line.
+#    (e.g. --enable-experiment=non-nullable).
+#
+#    If `sdk/lib/_internal/allowed_experiments.json` is updated, this field
+#    specifies the version that enables this experiment for those libraries
+#    and packages.
+#
+# 4. expired: (optional boolean)
 #    If true, then the experiment can no longer be enabled by specifying the
 #    flag on the command line, and the corresponding entry is slated for
 #    eventual removal from this file. If this field is omitted, then 'expired'
 #    is considered to be false.
 #
-# 4. validation: (optional string)
+# 5. validation: (optional string)
 #    If provided this should be a program that prints "feature enabled" on
 #    stdout if the feature is enabled, and throws or fails to compile otherwise.
 #    The intended use for this is to be able to run generic tests for each
@@ -74,11 +86,11 @@
 # the feature as it is being developed.
 #
 # Experimental release:
-#    When an experiment is released, then the 'experimentalReleaseVersion' field
-# is added indicating which version of the SDK contains this new language
-# feature for libraries and packages in mentioned in
-# `sdk/lib/_internal/allowed_experiments.json`. For other libraries and
-# packages, passing the experiment flag is still required to turn on the
+#    When we want to allow certain libraries and packages to enable the language
+# feature by default, we add an entry to the
+# `sdk/lib/_internal/allowed_experiments.json` allow list and then we bump the
+# `experimentalReleaseVersion` field to the latest version. For other libraries
+# and packages, passing the experiment flag is still required to turn on the
 # experiment.
 #
 # Shipped: