languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-11-02 15:17:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update nnbd_migration README with more details.

Browse source 
* Use title case on all headings.
* Link to https://dart.dev/null-safety and
  https://dart.dev/tools/pub/cmd/pub-outdated
* Remove any text which suggests to publish. Official docs warn
  strongly against using in production.
* Mention `pub outdated --mode=null-safety`.
* Mention migrating a clean code repository.
* Add more text about committing along the way.
* Make clear that the tool provides no revert capability.

Change-Id: I7914dc904a93046ce2508c51cae158ac39e889af
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/150822
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Mike Fairhurst <mfairhurst@google.com>
This commit is contained in:
Sam Rawlins 2020-06-11 03:33:25 +00:00 committed by commit-bot@chromium.org
parent e62b89c56d
commit 6ac9749546
1 changed files with 44 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
pkg/nnbd_migration/README.md
View file

@ -1,18 +1,18 @@
# Null Safety Migration Tooling
# Null safety migration tooling
**Note**:
* The null safety migration tooling is in an early state and may have bugs and
other issues.
* As null safety is still in preview, we recommend only doing trial
migrations. The final migration of apps and packages, should not be done
migrations. The final migration of apps and packages should not be done
until the feature is more complete.
* For best results, use SDK version 2.9.0-10.0.dev or higher.
## How Migration Works
## How migration works
The migration uses a _new interactive algorithm_ designed specifically for Dart
null safety.
The migration uses a _new interactive algorithm_ designed specifically for [Dart
null safety](https://dart.dev/null-safety).
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**
@ -42,12 +42,12 @@ 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!
web UI. After starting the tool with `dart migrate`, open the presented 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.
For example,
@ -92,12 +92,25 @@ 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.
<!-- TODO(srawlins): We should explain (or point to explanation of) "migrated"
code. I don't see any documents pointing out how null safety is enabled via
pubspec.yaml, or library-by-library comments. -->
## Migrating a package
1. Select a package to work on, and open a command terminal in the top-level of
the package directory.
2. Run `pub get` in order to make available all dependencies of the package.
3. Run the migration tool from the top-level of the package directory:
3. It is best to migrate a package to null safety _after_ the package's
dependencies have migrated to null safety. Run
`pub outdated --mode=null-safety` to learn the migration status of the
package's dependencies. See the
[pub outdated documentation](https://dart.dev/tools/pub/cmd/pub-outdated)
for more information.
4. It is best to migrate a package starting from a clean code repository state
(`git status`, for example), in case you must revert the migration. Ensure
there are no pending changes in the package's code repository.
5. Run the migration tool from the top-level of the package directory:
```
dart migrate
@ -117,10 +130,16 @@ browser to view, analyze, and improve the proposed null-safe migration.
1. Use the "trace view" in the bottom right to find the root cause
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.
* Some changes are as simple as adding a `/*!*/` hint on a type. The
tool has buttons to do this for you.
* Others may require larger refactors. These changes can be made in
your editor.
* Changes may even be committed to source code management before finally
_applying_ the migration. In this way, a migration of a large package
can be carried out over multiple sessions, or between multiple
engineers. Committing hints and other adjustments along the way helps
to separate the concerns of describing user intent vs committing to the
migration result.
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
@ -134,12 +153,16 @@ browser to view, analyze, and improve the proposed null-safe migration.
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.
7. Rerun `pub get`, then analyze and test your package.
1. If there are new static analysis issues, or 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.
one. The tool does not provide any revert capability; this must be done
via source code management (for example, `git checkout`).
<!-- TODO(srawlins): direct the user to publish, only after null safety leaves
tech preview. See the big note at https://dart.dev/null-safety.
8. Commit and/or publish your migrated null-safe code. -->
## Providing feedback