Dart 3 alpha null safety updates

src/null-safety/index.md

@@ -3,7 +3,10 @@ title: Sound null safety
 description: Information about Dart's null safety feature
 ---
 
-The Dart language comes with sound null safety.
+The Dart language comes with sound null safety. 
+
+In Dart 3, you always get null safety. In Dart 2.x,
+it must be enabled [with a pubspec setting](#enable-null-safety).
 
 Null safety prevents errors that result from unintentional access
 of variables set to `null`.
@@ -25,19 +28,6 @@ any non-nullable variable hasn't been initialized with a
 non-null value or is being assigned a `null`.
 This allows you to fix these errors before deploying your app.
 
-{{site.alert.warn}}
-In Dart 2.x SDKs, you can enable or disable sound null safety 
-through configuration of the project SDK constraint.
-To learn more, see [Enabling/disabling null safety](#enable-null-safety).
-
-Dart 3--planned for a mid-2023 release--
-will require sound null safety. It will prevent code from running without it.
-All existing code must be [migrated](#migrate) to sound null safety
-to be compatible with Dart 3.
-To learn more, see the [Dart 3 sound null safety tracking issue][].
-{{site.alert.end}}
-
-[Dart 3 sound null safety tracking issue]: https://github.com/dart-lang/sdk/issues/49530
 
 ## Introduction through examples
 
@@ -86,10 +76,66 @@ Dart null safety support is based on the following three core design principles:
   fewer bugs, but smaller binaries and faster execution.
 
 
-## Enabling/disabling null safety {#enable-null-safety}
+## Dart 3 and null safety
+
+Dart 3---planned for a mid-2023 release---always has sound null safety.
+Dart 3 will prevent code from running without it.
+
+Packages developed without null safety support will cause issues
+when resolving dependencies:
+
+```terminal
+$ dart pub get
+
+Because pkg1 doesn't support null safety, version solving failed.
+The lower bound of "sdk: '>=2.9.0 <3.0.0'" must be 2.12.0 or higher to enable null safety.
+```
+
+Libraries that opt out of null safety will cause analysis or compilation
+errors:
+
+```terminal
+$ dart analyze .
+Analyzing ....                         0.6s
+
+  error • lib/pkg1.dart:1:1 • The language version must be >=2.12.0. 
+  Try removing the language version override and migrating the code.
+  • illegal_language_version_override
+```
+
+```terminal
+$ dart run bin/my_app.dart
+../pkg1/lib/pkg1.dart:1:1: Error: Library doesn't support null safety.
+// @dart=2.9
+^^^^^^^^^^^^
+```
+
+To resolve these issues, check for 
+[null safe versions](/null-safety/migration-guide#check-dependency-status)
+of any packages you installed from pub.dev, and [migrate](#migrate) all
+of your own source code to use sound null safety.
+
+### Dart 3 backwards compatibility
+
+Packages and apps migrated to use null safety with Dart 2.12 or later will
+likely be backwards compatible with Dart 3. Specifically, for any package where
+the lower bound of the SDK constraint is 2.12.0 or higher, pub will allow
+resolution even when the upper bound is limited to versions below 3.0.0. For
+example, a package with the following constraint will be allowed to resolve with
+a Dart 3.x SDK:
+
+```yaml
+environment:
+  sdk: '>=2.14.0 <3.0.0'
+```
+
+This allows developers to use Dart 3 sound null safety with packages that have
+been migrated to 2.12 null safety without needing a second migration.
+
+## Dart 2.x and null safety {#enable-null-safety}
 
-You can use sound null safety in Dart 2.12 and Flutter 2.0 or later.
-Dart 3 and later will [_only_ support sound null safety][Dart 3 sound null safety tracking issue].
+In Dart 2.12 to 2.19, null safety is a configuration option in the pubspec. Null
+safety is not available in SDK versions prior to Dart 2.12.
 
 <a id="constraints"></a>
 To enable sound null safety, set the
@@ -104,18 +150,18 @@ environment:
 
 [language version]: /guides/language/evolution#language-versioning
 
-### Migrating an existing package or app {#migrate}
+## Migrating existing code {#migrate}
 
-The Dart SDK includes the `dart migrate` tool.
-This tool helps you migrate code that supports sound null safety. 
-Use `dart migrate` if you wrote Dart code with Dart 2.12 or earlier.
+Dart code written without null safety support can be migrated to use null
+safety. We recommend using the `dart migrate` tool, included in the Dart SDK
+versions 2.12 to 2.19.
 
 ```terminal
 $ cd my_app
 $ dart migrate
 ```
 
-To learn how to migrate your code to null safety,
+For more details on how to migrate your code to null safety,
 see the [migration guide][].
 
 
@@ -127,15 +173,9 @@ For more information about null safety, see the following resources:
 * [Understanding null safety][]
 * [Migration guide for existing code][migration guide]
 * [Null safety FAQ][]
-* [DartPad with null safety]({{site.dartpad}})
 * [Null safety sample code][calculate_lix]
-* [Null safety tracking issue][110]
-* [Dart blog][]
 
-[110]: https://github.com/dart-lang/language/issues/110
 [calculate_lix]: https://github.com/dart-lang/samples/tree/master/null_safety/calculate_lix
-[`dart create`]: /tools/dart-create
-[Dart blog]: https://medium.com/dartlang
 [migration guide]: /null-safety/migration-guide
 [Null safety FAQ]: /null-safety/faq
 [Null safety codelab]: /codelabs/null-safety

src/null-safety/migration-guide.md

@@ -70,12 +70,13 @@ so that you can easily undo any changes.
 
 ### Switch to the latest stable Dart release
 
-Switch to the **latest stable release**
-of either the Dart SDK or the Flutter SDK.
+Switch to the **Dart 2.19 stable release**
+of the Dart SDK. This is included in the Flutter 3.7 SDK.
 
-Check that you have Dart 2.12 or later:
-  ```terminal
+Check that you have Dart 2.19:
+```terminal
 $ dart --version
+Dart SDK version: 2.19.0
 ```
 
 ### Check dependency status
@@ -328,6 +329,9 @@ except for a 2.9 [version comment][].
 For more information about incremental migration, see
 [Unsound null safety][].
 
+Note that only fully migrated apps and packages 
+are compatible with Dart 3.
+
 [version comment]: /guides/language/evolution#per-library-language-version-selection
 
 
@@ -475,7 +479,13 @@ we strongly recommend following these pubspec rules:
 
 If you made it this far,
 you should have a fully migrated, null-safe Dart package.
+
 If all of the packages you depend on are migrated too,
 then your program is sound with respect to null-reference errors.
+You should see output like this when running or compiling your code:
+
+```terminal
+Compiling with sound null safety
+```
 
 From all of the Dart team, *thank you* for migrating your code.

src/null-safety/unsound-null-safety.md

@@ -9,7 +9,7 @@ These **mixed-version programs**
 rely on **unsound null safety**.
 
 {{site.alert.warn}}
-Dart 3---planned for a mid-2023 release---will require sound null safety. 
+Dart 3---planned for a mid-2023 release---requires sound null safety. 
 It will prevent code from running without
 null safety, or with unsound null safety.
 All existing code must be [migrated][] to sound null safety