[nnbd_migration] Update README

Change-Id: Idc81bbebadbe3d6111a6e7e31ee0c68a30d8ff26
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/148795
Reviewed-by: Devon Carew <[email protected]>
Reviewed-by: Janice Collins <[email protected]>

Author: MichaelRFairhurst

pkg/nnbd_migration/README.md

@@ -1,85 +1,138 @@
 # Null Safety Migration Tooling
 
-Note: the null safety migration tooling and workflow is in an early state;
-this doc will be updated as the steps and workflow are simplified.
+Note: the null safety migration tooling is in an early state and may have bugs
+and other issues.
 
-## Building the NNBD sdk
+For best results, use SDK version 2.9.0-10.0.dev or higher.
 
-In order to run the tool currently you have to be able to build your own copy
-of the Dart SDK.
+## How Migration Works
 
-To do this, run:
+The migration uses a _new interactive algorithm_ designed specifically for Dart
+null safety.
 
-```
-./tools/build.py -mrelease --nnbd create_sdk
+Typical code migration tools are designed to be run once, handle most cases, and
+let the developer do manual cleanup on the result. This does **not work well**
+for Null-Safety and attempting this workflow will result in a lot more manual
+work. Similarly, after your migration has been applied, the migration **cannot
+be rerun** without first reverting it.
+
+### Why does the interactive approach save so much time?
+
+Remember that Dart already has nullable types. Every type in old Dart code is
+nullable! What old Dart lacks is _non-null_ types.
+
+And like most migrations, our tool tries to preserve your code's current
+behavior. In the case of null safety, we may mark a lot of your types as
+nullable -- because they really were nullable before.
+
+Nulls are traced through your program as far as they can go, and types are
+marked nullable in this process. If the tool makes a single mistake or choice
+you disagree with, it can lead many excess nullable types.
+
+### Interactive feedback to the tool
+
+Unintentional null is the top cause of crashes in Dart programs. By marking your
+intention with comments like `/*?*/` and `/*!*/`, we can stop these
+unintentional nulls from spreading through your program in your migrated code.
+Adding a small number of these hints will have a huge impact on migration
+quality.
+
+The high level workflow of the tool is therefore driven through an interactive
+web UI. After running `dart migrate`, open the resulting url in a browser. Scan
+through the changes, use the "nullability trace" feature to find the best place
+to add a nullability hint (adding a hint in the best place can prevent dozens of
+types from being made nullable). Rerun the migration and repeat, committing the
+hints as you go. When the output is correct and acceptable, apply the migration
+and publish your null safe code!
+
+For example,
+
+```dart
+List<int> ints = const [0, null];
+int zero = ints[0];
+int one = zero + 1;
+List<int> zeroOne = [zero, one];
 ```
 
-The NNBD sdk now lives under the ReleaseX64NNBD sub-directory of your build
-directory, e.g.
+The default migration will be backwards compatible, but not ideal.
 
+```dart
+List<int?> ints = const [0, null];
+int? zero = ints[0];
+int one = zero! + 1;
+List<int?> zeroOne = <int?>[zero, one];
 ```
-xcodebuild/ReleaseX64NNBD/dart-sdk/
+
+`zero` should not be marked nullable, but it is. We then have cascading quality
+issues, such as null-checking a value that shouldn't have been marked null, and
+marking other variables as null due to deep null tracing. We can fix this all by
+adding a single `/*!*/` hint.
+
+```dart
+List<int?> ints = const [0, null];
+int/*?*/ zero = ints[0]!; // Just add /*?*/ here, the migration tool does the rest!
+int one = zero + 1;
+List<int> zeroOne = <int>[zero, one];
 ```
 
+If you add one hint before migrating, you have done the equivalent of making
+five manual edits after migrating. To find the best place to put your hints, use
+the preview tool's nullability trace feature. This lets you trace back up to the
+root cause of any type's inferred nullability. Add hints as close to the
+original source of null as possible to have the biggest impact to the migration.
+
+**Note**: The migration tool **cannot be rerun on a migrated codebase.** At
+that point in time, every nullable and non-nullable type is indistinguishable
+from an **intentionally** nullable or non-nullable type. The opportunity to
+change large numbers of types for you at once without also accidentally changing
+your intent has been lost. A long migration effort (such as one on a large
+project) can be done incrementally, by committing these hints over time.
+
 ## Migrating a package
 
-- build a NNBD version of the SDK (see above)
 - select a package to work on
-- in that package, edit the `analysis_options.yaml` to enable the NNBD
-  experiment from the POV of the analyzer:
-```yaml
-analyzer:
-  enable-experiment:
-    - non-nullable
-```
-- run `pub get` for the package (and, verify that the
-  `.dart_tool/package_config.json` file was created)
+- run `pub get` for the package
 
 Then, run the migration tool from the top-level of the package directory:
 
 ```
-<sdk-repo>/xcodebuild/ReleaseX64NNBD/dart migrate .
+dart migrate
 ```
 
-The migration tool will run, print the proposed changes to the console, and
-display a url for the preview tool. Open that url from a browser to see a rich
-preview of the proposed null safety changes.
+The migration tool will run and display a url for the web UI. Open that url from
+a browser to view, analyze, and improve the proposed null-safe migration.
 
 ## Using the tool
 
 1. Run the tool (see above).
-2. Once analysis and migration suggestions are complete, open the indicated url
-in a browser.
-3. Start with an important or interesting file in your package on the left
-side by clicking on it.
+2. Once analysis and migration is complete, open the indicated url in a browser.
+3. Start with an important or interesting file in your package on the left side
+   by clicking on it.
 4. Look at the proposed edits in the upper right, and click on them in turn.
 5. If you see an edit that looks wrong:
     1. Use the "trace view" in the bottom right to find the root cause
-    2. Go to your editor and make a change to the original file by adding a hint
-    (`String foo` ==> `String/*!*/ foo`) or making other changes as needed.
-    3. You can have the migration tool perform this itself, although right now
-       for large packages this takes a prohibitively long time.
-       1. ***Warning: DO NOT mix edits in your editor and edits applied by the
-       migration tool. We have not yet written the necessary logic to
-       prevent the migration tool from clobbering files edited while the
-       preview tool is running.*** 
-       2. To try this, from the 'Edit Details' area in the bottom right select
-       the `Force type to be non-nullable` or `Force type to be nullable`
-       links. These will add the indicated hints on disk and recompute the
-       migration suggestions. 
-6. After some edits are complete, control-C the migration and rerun it.  If
-some things are still wrong, return to step 5.
-7. Once all edits are complete and you've rerun migration and are satisfied with
-the output:
+    2. Either click on an "add hint" button to correct it at the root, or open
+       your editor and make the change manually.
+        1. Some changes are as simple as adding a `/*!*/` hint on a type. The
+           tool has buttons to do this for you.
+        2. Others may require larger refactors. These changes can be made in
+           your editor, and may often be committed and published immediately.
+    3. Periodically rerun the migration and repeat.
+6. Once you are satisfied with the proposed migration:
     1. Save your work using git or other means. Applying the migration will
-    overwrite the existing files on disk.
-    2. Rerun the migration with `--apply-changes`, or click the
-    `Apply Migration` button in the interface.
-8. Remove any SDK constraint in your pubspec.yaml.
-9. Remove any opt-out comments in your library files (e.g.:  `// @dart = 2.6`).
-10. Rerun `pub get` and test your package.
+       overwrite the existing files on disk.
+    2. Rerun the migration by clicking the `Apply Migration` button in the
+       interface.
+    3. Tip: leaving the web UI open may help you if you later have test failures
+       or analysis errors.
+7. Rerun `pub get` and test your package.
+    1. If a test fails, you may still use the preview to help you figure out
+       what went wrong.
+    2. If large changes are required, revert the migration, and go back to step
+       one.
+8. Commit and/or publish your migrated null-safe code
 
 ## Providing feedback
 
 Please file issues at https://github.com/dart-lang/sdk/issues, and reference the
-`analyzer-nnbd-migration` label (you may not be able to apply the label yourself). 
+`analyzer-nnbd-migration` label (you may not be able to apply the label yourself).