docs/process/language-versions-and-experiments.md - sdk.git - Git at Google

 # Language Versioning and Experiments

 This document explains our model for how to language versioning and experiment
 flags interact, and the processes we use to work with them. The key principles:

 *   Every major and minor (".0") release of the SDK creates a new language
     version. A shipped language version's semantics are entirely fixed by how it
     behaves in that version of the SDK.

 *   At any point in time, there is an "in-progress" language version with a
     family of related languages, one for each combination of experiments.

 *   Language versioning, experiment flags, and other magic for handling the core
     libraries and special packages like Flutter all boil down to mechanisms to
     select which of these many languages a given library wants to target.

 ## Language Versions

 There is an ordered series of shipped language versions, 2.5, 2.6, etc. Each one
 is a different language. They may be mutually incompatible (in practice they are
 mostly compatible). Each Dart library targets&mdash;is "written in"&mdash;a
 *single* version of the language. (We'll get to how they target one soon.)
 Programs may contain libraries written in a variety of languages, and a Dart SDK
 supports multiple different Dart versions simultaneously.

 Each time we ship a major or minor stable release of the SDK, the corresponding
 language version gets carved in stone. The day we shipped Dart 2.5.0, we
 henceforth and forevermore declared that there is only one Dart 2.5, and it
 refers to the first Dart version that supports the "constant update" changes.

 As of today, the 2.5, 2.6, and 2.7 language versions are all locked down.

 Patch releases, like 2.5.1, do not introduce new language versions. Both Dart
 SDK 2.5.0 and 2.5.1 contain language version 2.5. This implies that we cannot
 ship breaking language changes in patch releases. Doing so would spontaneously
 break any user whose library already targeted that language version.

 ### "In-progress" version

 At any point in time, there is also an **in-progress language version.** It
 corresponds to the current dev build or (equivalently) the next stable version
 to be released. Today's current in-progress language version is 2.8 because we
 have shipped 2.7.1 and have not yet shipped 2.8.0.

 Unlike the previous stable releases, the in-progress version is not carved in
 stone. As we develop the SDK, its behavior may change.

 ### Experimental languages

 The in-progress version is not alone. Hanging off it are a family of sibling
 **experimental languages.** Each one corresponds to a specific combination of
 experiment flags. While there is only one Dart 2.7, there are several Dart 2.8s:

 *   "2.8": The Dart you get right now on bleeding edge with no experiments enabled.

 *   "2.8+non-nullable": The same but with the "non-nullable" experiment enabled.

 *   "2.8+variance": Likewise but with "variance" instead.

 *   "2.8+non-nullable+variance": Both "non-nullable" and "variance" experiments.

 All of these languages exist simultaneously and in parallel. Dart 2.6, Dart 2.7,
 Dart 2.8, and Dart 2.8+non-nullable, etc. all *are* in some sense. They have
 (sometimes incomplete) specs. There are tools that implement them. Think of each
 as a different language with its own name, syntax, and semantics.

 Don't think of an experiment flag as "turning on a feature". The feature is
 there, it's just in some other language. The only question is which libraries
 want to go over there and use it.

 You can visualize the space of different flavors of Dart something like this:

 ```
 ┌──────── shipped ─────────┐ ┌─ in-progress ─────────────┐
 older... ┄─ 2.5 ─ 2.6 ─ 2.7 ─ 2.8
                                │
            ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐  2.8+non-nullable
            ╎               ╎   │
            ╎      no       ╎  2.8+variance
            ╎   languages   ╎   │
            ╎    here...    ╎  2.8+triple-shift
            ╎               ╎   │
            ╎               ╎  2.8+non-nullable+variance
            └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘   │
                                ┆
                               other experiment combinations...
 ```

 There is a line of numeric languages for all of the shipped stable versions of
 Dart, receding back into history. Then there is a single in-progress version and
 next to it are all of the various combinations of experiments. There are no
 other languages. In particular, there are no combinations of "shipped version +
 experiment". **You cannot "enable an experiment" in a library targeting a shipped
 version of the language.**

 ## Selecting a Language

 This is the fundamental concept: there are a variety of different Dart languages
 for various versions and combinations of experimental in-progress features.
 Everything else is just a mechanism for users to select *which* of these
 languages they use.

 The first part to picking a language for a library is picking the numeric part.
 The language versioning spec defines how that works. For completeness' sake, the
 basic rules are (in priority order):

 1.  A comment like `// @dart=2.5` selects that (numeric) version for the library.

 2.  For other libraries in a package, the "package_config.json" file specifies
     their language version. This file is generated by pub from the SDK
     constraints in the pubspecs of the various packages the user is using.

 3.  If a package does not specify an SDK constraint, then pub doesn't put a
     language version in the "package_config.json" for that file. In that case,
     libraries in that package default to the "current SDK" version.

 4.  Likewise, any library not part of a package defaults to the "current SDK"
     version.

 ### SDK version &rarr; Language version

 The "current SDK version" is generally the semver version you get when you run
 one of the various Dart tools with `--version`.

 To convert that three-component semver SDK version to a major.minor language
 version, use this rule: **The language version of an SDK is the major and minor
 version of the version reported by tools in that SDK.** This means that:

 *   Stable releases of the Dart SDK have the language version you expect: Dart
     2.5.3's language version is 2.5.

 *   Dev and bleeding edge releases have the language version of the upcoming
     stable release. On my machine today, `dart --version` reports
     "2.8.0-edge.a38…", which means its language version is "2.8". In other
     words, **the default language version of non-stable versions of the SDK is
     the in-progress language.**

 Internally in the Dart SDK repo, the source of truth for the SDK version number
 is `tools/VERSION`. That file gets updated during the release process when
 various branches are cut and releases shipped. We could calculate the language
 version from that using the above rule, but we're worried that means the
 language version could change inadvertently as a consequence of release
 administrivia. Instead, the repo stores the language version explicitly in
 `tools/experimental_features.yaml`.

 In theory this means the SDK's reported version can get out of sync with its
 language version. In practice, slippage should be rare and only visible to users
 building the Dart SDK on bleeding edge.

 ### SDK constraint &rarr; Language version

 The rule to convert an SDK constraint to a language is: **The default language
 version used by a package is the language version of its SDK constraint's
 minimum version.** Thus the following SDK constraints yield these language
 versions:

 *   `>=2.6.0 <3.0.0` &rarr; 2.6

 *   `>=2.6.3 <3.0.0` &rarr; 2.6 (still on 2.6)

 *   `>=2.7.1 <3.0.0` &rarr; 2.7 (still on 2.7)

 *   `>=2.8.0-dev.1 <3.0.0` &rarr; (2.8, in-progress version)

 This rule lets users target language versions that exist only in dev releases.
 It also lets them use a patch version as their minimum version in order to get
 bug fixes or core library changes.

 ## Experiment Flags

 Language versioning and the above section cover cases where you just want your
 library to get onto a specific numeric language version like 2.7, even including
 the current in-progress version 2.8. But what if you want to play with some
 experimental in-progress features? For that, you need to get onto one of the
 experimental sibling languages of the in-progress version. You get there by
 passing experiment flags to the various tools (and in their
 `analysis_options.yaml` file).

 This is *all* the experiment flags do. Passing a set of experiment flags to a
 Dart tool means **Treat every user library using the in-progress language as
 using the given experimental language instead.**

 "User library" means libraries authored by normal Dart users outside of the Dart
 and Flutter teams who may have some special powers described below.

 "Using the in-progress language" means this rule only comes into play for the
 in-progress language. Today, passing the "non-nullable" flag shunts every user
 library targeting 2.8 over to 2.8+non-nullable, but has no effect on any library
 targeting 2.7 or older. *There is no such thing as 2.7+non-nullable.* The day
 2.7.0 shipped, 2.7 got locked down and all of the experimental versions
 surrounding it evaporated, to be replaced by a new set of experimental languages
 surrounding the new in-progress version 2.8.

 Shipping a version of the SDK and language does not imply that all experiment
 flags that exist at that point automatically get turned on in that version. Many
 language changes gated behind experiment flags float through several releases
 before finally becoming ready to ship. The "non-nullable" and "variance"
 experiments existed before we shipped 2.7.0 and still exist today.

 When a new version of the SDK is released, unless an experimental feature is
 deliberately "shipped" (meaning the behavior is turned on by default and the
 flag goes away), the flag simply carries forward as an experimental feature in
 the next in-progress version. So the day we shipped Dart 2.7.0, "variance"
 ceased to be a flag that affects Dart 2.7 and instead became a flag that affects
 Dart 2.8.

 ### Experiment flags are global across all user libraries

 Note that passing an experiment flag moves *all* in-progress version user
 libraries onto that experimental language. If you pass "non-nullable", all of
 your 2.8 libraries *and every 2.8 library in every package you use* instantly
 starts targeting 2.8+non-nullable. We support mixed-mode Dart programs
 consisting of libraries using a variety of *shipped* versions like 2.7 and 2.6.
 You can even mix them with *one* in-progress version like 2.8 or
 2.8+non-nullable.

 We do *not* support user programs that are arbitrary combinations of
 *experimental* languages. We don't want to have to define or implement what it
 means to have, for example, a 2.8+variance library importing a 2.8+non-nullable
 library and extending a generic class from it. Combinations of combinations is a
 path to madness.

 We may internally allow some mixture to occur because of things like core
 libraries (see below), but that's because we can carefully control what code is
 in that weird state. We do not want to let *users* write programs that mix
 different experimental languages. If you have some user library that you don't
 want to be affected by an experiment you are playing with, make sure that
 library is not on the in-progress version.

 ### SDK core libraries and other special friends

 Experiment flags are *a* way to shift a library from the in-progress version
 over to one of its experimental siblings, but not the only way. Remember, all
 experimental flavors of the in-progress version exist simultaneously. Experiment
 flags are primarily intended to let *users* opt their libraries into one of
 those experimental languages.

 We on the Dart team have our own special powers. The migrated SDK core libraries
 do not need the user to pass any experiment flag to move them into
 2.8+non-nullable. Our tools know to do that automatically when compiling those
 particular libs. Likewise, when Flutter (and a couple of packages like
 vector_math that it exports from its API) migrate, we can also use whitelists or
 other special sauce to move them into 2.8+non-nullable.

 However, all those libraries do need to take care to select the right *numeric*
 version. Because, again, there is no such thing as 2.7+non-nullable. So if, say,
 a core lib doesn't get marked as 2.8, it ain't gonna be 2.8+non-nullable. Dart's
 "language versioning" support is how libraries do that.

 ## Using Null Safety

 OK, so let's put that all together to see how someone goes about being able to
 use `?` and `late` in their library today.

 1.  You must be running on a dev or bleeding edge build of the SDK. No stable
     release of Dart has support for any language later than 2.7.

 2.  Tell Dart that your libraries should be treated as 2.8. In the core libs,
     we've been using the version comments and/or some hardcoding. In a package,
     you can set the SDK constraint to:

     ```yaml
     environment:
       sdk: '>=2.8.0-dev.0 <2.8.0'
     ```

     *SDK min constraint:* You can require a higher dev release if you want. The
     important part is that the minimum is at least *a dev version of 2.8.0*. You
     could also omit the SDK constraint completely. That works OK for application
     packages but not for library packages since pub will not let you publish a
     package without an SDK constraint.

     SDK max constraint: The relatively low max version gives us some wiggle room
     to break things before 2.8.0. I don't know if it's wise to claim that a
     package we publish right now will keep working all the way through, say,
     3.0.0. It's not strictly necessary. Everything in this doc still works if
     you do <3.0.0

 3.  Tell your Dart compiler to shunt all version 2.8 user libraries over to
     2.8+non-nullable by passing `--enable-experiment=non-nullable` when you
     invoke the tool. Put something similar in your `analysis_options.yaml` file
     for IDE goodness. See the [experimental flags doc][] for details.

 That's it. Now you have a library that Dart tools know targets 2.8+non-nullable,
 at least today.

 [experimental flags doc]: https://github.com/dart-lang/sdk/blob/main/docs/process/experimental-flags.md

 ### 2.8.0 ships without null safety

 Let's say we ship Dart 2.8.0 stable and it does not include stable support for null safety. That means null safety is still behind the "non-nullable" flag. What happens?

 The day this happens, 2.8 is no longer an "in-progress" language version. It has
 become carved in stone and that language version refers to exactly the behavior
 shipped by that SDK. All of the 2.8 experimental versions disappear. The
 experiment flags no longer affect libraries using language 2.8. Instead, at that
 exact same moment, a new 2.9 in-progress version appears. Any flags that we
 didn't ship and carried forward now apply to that. So there is 2.9+non-nullable,
 2.9+variance, etc.

 This closing of 2.8 and opening of 2.9 implies several things:

 *   **Any library targeting 2.8 and using null safety features needs to have its
     language version changed to target 2.9.** This can mean changing a ``//
     @dart=2.8` comment or bumping the minimum SDK constraint in the pubspec.

 *   **In the 2.8.0 stable SDK that we just shipped, the language version for the
     core libraries must be 2.9.** They must be because they use null safety
     features, which can no longer be enabled for 2.8 libraries. This seems
     weird. How can 2.8.0 support a *future* version of Dart? The reality is that
     2.8.0 has secret *internal* support for some subset of 2.9 that we know the
     core libraries happen to fit within. It's an implementation detail that
     those core libraries happen to use capabilities within the SDK that we don't
     expose externally yet. It's strange, but I think should be OK.

 *   **Any packages needed by Flutter for users to play with null safety after
     2.8.0 ships need to have min SDK constraints above 2.8.0.** They need to get
     to language level 2.9, and the only way to do that is with a constraint that
     excludes 2.8.0. But if users are running on Dart 2.8.0 stable, Pub won't
     select any of those packages because 2.8.0 is outside of their SDK
     constraint!

     This is a real problem, a consequence of using SDK constraints to control
     *both* language version and package resolution. To address this, shortly after
     shipping the stable build, we will also ship a Dart 2.9.0-dev.0 dev release
     and roll that into Flutter's dev channel. Anyone who wants to experiment
     with non-nullability needs to be on the dev channel. Null-safety is still an
     experimental feature, and the point of stable releases is to be, well,
     stable. If you want to experiment with experimental features, get yourself
     on dev channel.

 ### 2.10.0 ships with null safety

 Then let's say we finally ship null safety officially in 2.10.0. Every package
 out there playing with the null safety experiment has already revved its minimum
 SDK constraint to something like `>=2.10.0-dev.0`. What happens next?

 *   **If the SDK constraint is like `>=2.10.0-dev.0 <2.10.0`, they just need to
     raise that to include 2.10.0.** This path is the safe choice because it's
     risky to assume the next stable release will be compatible with preceding
     in-progress dev builds. The point of dev builds is that they are in flux. So
     most packages using null safety should be in this state. Once we ship null
     safety, we just need to raise their max SDK constraints to include 2.10.0
     after verifying that the package still works with the stable release.

 *   **If the SDK constraint is like `>=2.10.0-dev.0 <3.0.0` the package author
     has nothing to do.** The package claims to support both the previous dev
     versions of null safety and the shipped stable version. A constraint like
     this is dubious because we reserve the right to make arbitrary breaking
     changes to features that are gated behind experiment flags. But if the
     package author is confident that no breakage has or will happen (likely
     because said "author" is a member of the Dart team), a wide constraint like
     this *can* be reasonable. And, in that case the package keeps working. It's
     already on language 2.10 and 2.10 now supports null safety out of the box.
     There's nothing to do.

 *   **If the SDK constraint is like `>=2.8.0 <3.0.0`, the package is on a
     previous "legacy" language version.** The package has "opted out of NNBD"
     and keeps working like it did before.

 There's nothing special about "2.10.0" in this scenario. Whenever we choose to
 ship an experimental feature, in whatever version, this is how it should play
 out regarding packages.
	# Language Versioning and Experiments

	This document explains our model for how to language versioning and experiment
	flags interact, and the processes we use to work with them. The key principles:

	* Every major and minor (".0") release of the SDK creates a new language
	version. A shipped language version's semantics are entirely fixed by how it
	behaves in that version of the SDK.

	* At any point in time, there is an "in-progress" language version with a
	family of related languages, one for each combination of experiments.

	* Language versioning, experiment flags, and other magic for handling the core
	libraries and special packages like Flutter all boil down to mechanisms to
	select which of these many languages a given library wants to target.

	## Language Versions

	There is an ordered series of shipped language versions, 2.5, 2.6, etc. Each one
	is a different language. They may be mutually incompatible (in practice they are
	mostly compatible). Each Dart library targets—is "written in"—a
	single version of the language. (We'll get to how they target one soon.)
	Programs may contain libraries written in a variety of languages, and a Dart SDK
	supports multiple different Dart versions simultaneously.

	Each time we ship a major or minor stable release of the SDK, the corresponding
	language version gets carved in stone. The day we shipped Dart 2.5.0, we
	henceforth and forevermore declared that there is only one Dart 2.5, and it
	refers to the first Dart version that supports the "constant update" changes.

	As of today, the 2.5, 2.6, and 2.7 language versions are all locked down.

	Patch releases, like 2.5.1, do not introduce new language versions. Both Dart
	SDK 2.5.0 and 2.5.1 contain language version 2.5. This implies that we cannot
	ship breaking language changes in patch releases. Doing so would spontaneously
	break any user whose library already targeted that language version.

	### "In-progress" version

	At any point in time, there is also an in-progress language version. It
	corresponds to the current dev build or (equivalently) the next stable version
	to be released. Today's current in-progress language version is 2.8 because we
	have shipped 2.7.1 and have not yet shipped 2.8.0.

	Unlike the previous stable releases, the in-progress version is not carved in
	stone. As we develop the SDK, its behavior may change.

	### Experimental languages

	The in-progress version is not alone. Hanging off it are a family of sibling
	experimental languages. Each one corresponds to a specific combination of
	experiment flags. While there is only one Dart 2.7, there are several Dart 2.8s:

	* "2.8": The Dart you get right now on bleeding edge with no experiments enabled.

	* "2.8+non-nullable": The same but with the "non-nullable" experiment enabled.

	* "2.8+variance": Likewise but with "variance" instead.

	* "2.8+non-nullable+variance": Both "non-nullable" and "variance" experiments.

	All of these languages exist simultaneously and in parallel. Dart 2.6, Dart 2.7,
	Dart 2.8, and Dart 2.8+non-nullable, etc. all are in some sense. They have
	(sometimes incomplete) specs. There are tools that implement them. Think of each
	as a different language with its own name, syntax, and semantics.

	Don't think of an experiment flag as "turning on a feature". The feature is
	there, it's just in some other language. The only question is which libraries
	want to go over there and use it.

	You can visualize the space of different flavors of Dart something like this:

	```
	┌──────── shipped ─────────┐ ┌─ in-progress ─────────────┐
	older... ┄─ 2.5 ─ 2.6 ─ 2.7 ─ 2.8
	│
	┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐ 2.8+non-nullable
	╎ ╎ │
	╎ no ╎ 2.8+variance
	╎ languages ╎ │
	╎ here... ╎ 2.8+triple-shift
	╎ ╎ │
	╎ ╎ 2.8+non-nullable+variance
	└╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘ │
	┆
	other experiment combinations...
	```

	There is a line of numeric languages for all of the shipped stable versions of
	Dart, receding back into history. Then there is a single in-progress version and
	next to it are all of the various combinations of experiments. There are no
	other languages. In particular, there are no combinations of "shipped version +
	experiment". **You cannot "enable an experiment" in a library targeting a shipped
	version of the language.**

	## Selecting a Language

	This is the fundamental concept: there are a variety of different Dart languages
	for various versions and combinations of experimental in-progress features.
	Everything else is just a mechanism for users to select which of these
	languages they use.

	The first part to picking a language for a library is picking the numeric part.
	The language versioning spec defines how that works. For completeness' sake, the
	basic rules are (in priority order):

	1. A comment like `// @dart=2.5` selects that (numeric) version for the library.

	2. For other libraries in a package, the "package_config.json" file specifies
	their language version. This file is generated by pub from the SDK
	constraints in the pubspecs of the various packages the user is using.

	3. If a package does not specify an SDK constraint, then pub doesn't put a
	language version in the "package_config.json" for that file. In that case,
	libraries in that package default to the "current SDK" version.

	4. Likewise, any library not part of a package defaults to the "current SDK"
	version.

	### SDK version → Language version

	The "current SDK version" is generally the semver version you get when you run
	one of the various Dart tools with `--version`.

	To convert that three-component semver SDK version to a major.minor language
	version, use this rule: **The language version of an SDK is the major and minor
	version of the version reported by tools in that SDK.** This means that:

	* Stable releases of the Dart SDK have the language version you expect: Dart
	2.5.3's language version is 2.5.

	* Dev and bleeding edge releases have the language version of the upcoming
	stable release. On my machine today, `dart --version` reports
	"2.8.0-edge.a38…", which means its language version is "2.8". In other
	words, **the default language version of non-stable versions of the SDK is
	the in-progress language.**

	Internally in the Dart SDK repo, the source of truth for the SDK version number
	is `tools/VERSION`. That file gets updated during the release process when
	various branches are cut and releases shipped. We could calculate the language
	version from that using the above rule, but we're worried that means the
	language version could change inadvertently as a consequence of release
	administrivia. Instead, the repo stores the language version explicitly in
	`tools/experimental_features.yaml`.

	In theory this means the SDK's reported version can get out of sync with its
	language version. In practice, slippage should be rare and only visible to users
	building the Dart SDK on bleeding edge.

	### SDK constraint → Language version

	The rule to convert an SDK constraint to a language is: **The default language
	version used by a package is the language version of its SDK constraint's
	minimum version.** Thus the following SDK constraints yield these language
	versions:

	* `>=2.6.0 <3.0.0` → 2.6

	* `>=2.6.3 <3.0.0` → 2.6 (still on 2.6)

	* `>=2.7.1 <3.0.0` → 2.7 (still on 2.7)

	* `>=2.8.0-dev.1 <3.0.0` → (2.8, in-progress version)

	This rule lets users target language versions that exist only in dev releases.
	It also lets them use a patch version as their minimum version in order to get
	bug fixes or core library changes.

	## Experiment Flags

	Language versioning and the above section cover cases where you just want your
	library to get onto a specific numeric language version like 2.7, even including
	the current in-progress version 2.8. But what if you want to play with some
	experimental in-progress features? For that, you need to get onto one of the
	experimental sibling languages of the in-progress version. You get there by
	passing experiment flags to the various tools (and in their
	`analysis_options.yaml` file).

	This is all the experiment flags do. Passing a set of experiment flags to a
	Dart tool means **Treat every user library using the in-progress language as
	using the given experimental language instead.**

	"User library" means libraries authored by normal Dart users outside of the Dart
	and Flutter teams who may have some special powers described below.

	"Using the in-progress language" means this rule only comes into play for the
	in-progress language. Today, passing the "non-nullable" flag shunts every user
	library targeting 2.8 over to 2.8+non-nullable, but has no effect on any library
	targeting 2.7 or older. There is no such thing as 2.7+non-nullable. The day
	2.7.0 shipped, 2.7 got locked down and all of the experimental versions
	surrounding it evaporated, to be replaced by a new set of experimental languages
	surrounding the new in-progress version 2.8.

	Shipping a version of the SDK and language does not imply that all experiment
	flags that exist at that point automatically get turned on in that version. Many
	language changes gated behind experiment flags float through several releases
	before finally becoming ready to ship. The "non-nullable" and "variance"
	experiments existed before we shipped 2.7.0 and still exist today.

	When a new version of the SDK is released, unless an experimental feature is
	deliberately "shipped" (meaning the behavior is turned on by default and the
	flag goes away), the flag simply carries forward as an experimental feature in
	the next in-progress version. So the day we shipped Dart 2.7.0, "variance"
	ceased to be a flag that affects Dart 2.7 and instead became a flag that affects
	Dart 2.8.

	### Experiment flags are global across all user libraries

	Note that passing an experiment flag moves all in-progress version user
	libraries onto that experimental language. If you pass "non-nullable", all of
	your 2.8 libraries and every 2.8 library in every package you use instantly
	starts targeting 2.8+non-nullable. We support mixed-mode Dart programs
	consisting of libraries using a variety of shipped versions like 2.7 and 2.6.
	You can even mix them with one in-progress version like 2.8 or
	2.8+non-nullable.

	We do not support user programs that are arbitrary combinations of
	experimental languages. We don't want to have to define or implement what it
	means to have, for example, a 2.8+variance library importing a 2.8+non-nullable
	library and extending a generic class from it. Combinations of combinations is a
	path to madness.

	We may internally allow some mixture to occur because of things like core
	libraries (see below), but that's because we can carefully control what code is
	in that weird state. We do not want to let users write programs that mix
	different experimental languages. If you have some user library that you don't
	want to be affected by an experiment you are playing with, make sure that
	library is not on the in-progress version.

	### SDK core libraries and other special friends

	Experiment flags are a way to shift a library from the in-progress version
	over to one of its experimental siblings, but not the only way. Remember, all
	experimental flavors of the in-progress version exist simultaneously. Experiment
	flags are primarily intended to let users opt their libraries into one of
	those experimental languages.

	We on the Dart team have our own special powers. The migrated SDK core libraries
	do not need the user to pass any experiment flag to move them into
	2.8+non-nullable. Our tools know to do that automatically when compiling those
	particular libs. Likewise, when Flutter (and a couple of packages like
	vector_math that it exports from its API) migrate, we can also use whitelists or
	other special sauce to move them into 2.8+non-nullable.

	However, all those libraries do need to take care to select the right numeric
	version. Because, again, there is no such thing as 2.7+non-nullable. So if, say,
	a core lib doesn't get marked as 2.8, it ain't gonna be 2.8+non-nullable. Dart's
	"language versioning" support is how libraries do that.

	## Using Null Safety

	OK, so let's put that all together to see how someone goes about being able to
	use `?` and `late` in their library today.

	1. You must be running on a dev or bleeding edge build of the SDK. No stable
	release of Dart has support for any language later than 2.7.

	2. Tell Dart that your libraries should be treated as 2.8. In the core libs,
	we've been using the version comments and/or some hardcoding. In a package,
	you can set the SDK constraint to:

	```yaml
	environment:
	sdk: '>=2.8.0-dev.0 <2.8.0'
	```

	SDK min constraint: You can require a higher dev release if you want. The
	important part is that the minimum is at least a dev version of 2.8.0. You
	could also omit the SDK constraint completely. That works OK for application
	packages but not for library packages since pub will not let you publish a
	package without an SDK constraint.

	SDK max constraint: The relatively low max version gives us some wiggle room
	to break things before 2.8.0. I don't know if it's wise to claim that a
	package we publish right now will keep working all the way through, say,
	3.0.0. It's not strictly necessary. Everything in this doc still works if
	you do <3.0.0

	3. Tell your Dart compiler to shunt all version 2.8 user libraries over to
	2.8+non-nullable by passing `--enable-experiment=non-nullable` when you
	invoke the tool. Put something similar in your `analysis_options.yaml` file
	for IDE goodness. See the [experimental flags doc][] for details.

	That's it. Now you have a library that Dart tools know targets 2.8+non-nullable,
	at least today.

	[experimental flags doc]: https://github.com/dart-lang/sdk/blob/main/docs/process/experimental-flags.md

	### 2.8.0 ships without null safety

	Let's say we ship Dart 2.8.0 stable and it does not include stable support for null safety. That means null safety is still behind the "non-nullable" flag. What happens?

	The day this happens, 2.8 is no longer an "in-progress" language version. It has
	become carved in stone and that language version refers to exactly the behavior
	shipped by that SDK. All of the 2.8 experimental versions disappear. The
	experiment flags no longer affect libraries using language 2.8. Instead, at that
	exact same moment, a new 2.9 in-progress version appears. Any flags that we
	didn't ship and carried forward now apply to that. So there is 2.9+non-nullable,
	2.9+variance, etc.

	This closing of 2.8 and opening of 2.9 implies several things:

	* **Any library targeting 2.8 and using null safety features needs to have its
	language version changed to target 2.9.** This can mean changing a ``//
	@dart=2.8` comment or bumping the minimum SDK constraint in the pubspec.

	* **In the 2.8.0 stable SDK that we just shipped, the language version for the
	core libraries must be 2.9.** They must be because they use null safety
	features, which can no longer be enabled for 2.8 libraries. This seems
	weird. How can 2.8.0 support a future version of Dart? The reality is that
	2.8.0 has secret internal support for some subset of 2.9 that we know the
	core libraries happen to fit within. It's an implementation detail that
	those core libraries happen to use capabilities within the SDK that we don't
	expose externally yet. It's strange, but I think should be OK.

	* **Any packages needed by Flutter for users to play with null safety after
	2.8.0 ships need to have min SDK constraints above 2.8.0.** They need to get
	to language level 2.9, and the only way to do that is with a constraint that
	excludes 2.8.0. But if users are running on Dart 2.8.0 stable, Pub won't
	select any of those packages because 2.8.0 is outside of their SDK
	constraint!

	This is a real problem, a consequence of using SDK constraints to control
	both language version and package resolution. To address this, shortly after
	shipping the stable build, we will also ship a Dart 2.9.0-dev.0 dev release
	and roll that into Flutter's dev channel. Anyone who wants to experiment
	with non-nullability needs to be on the dev channel. Null-safety is still an
	experimental feature, and the point of stable releases is to be, well,
	stable. If you want to experiment with experimental features, get yourself
	on dev channel.

	### 2.10.0 ships with null safety

	Then let's say we finally ship null safety officially in 2.10.0. Every package
	out there playing with the null safety experiment has already revved its minimum
	SDK constraint to something like `>=2.10.0-dev.0`. What happens next?

	* **If the SDK constraint is like `>=2.10.0-dev.0 <2.10.0`, they just need to
	raise that to include 2.10.0.** This path is the safe choice because it's
	risky to assume the next stable release will be compatible with preceding
	in-progress dev builds. The point of dev builds is that they are in flux. So
	most packages using null safety should be in this state. Once we ship null
	safety, we just need to raise their max SDK constraints to include 2.10.0
	after verifying that the package still works with the stable release.

	* **If the SDK constraint is like `>=2.10.0-dev.0 <3.0.0` the package author
	has nothing to do.** The package claims to support both the previous dev
	versions of null safety and the shipped stable version. A constraint like
	this is dubious because we reserve the right to make arbitrary breaking
	changes to features that are gated behind experiment flags. But if the
	package author is confident that no breakage has or will happen (likely
	because said "author" is a member of the Dart team), a wide constraint like
	this can be reasonable. And, in that case the package keeps working. It's
	already on language 2.10 and 2.10 now supports null safety out of the box.
	There's nothing to do.

	* **If the SDK constraint is like `>=2.8.0 <3.0.0`, the package is on a
	previous "legacy" language version.** The package has "opted out of NNBD"
	and keeps working like it did before.

	There's nothing special about "2.10.0" in this scenario. Whenever we choose to
	ship an experimental feature, in whatever version, this is how it should play
	out regarding packages.