mirror of
https://github.com/dart-lang/sdk
synced 2024-09-05 16:41:07 +00:00
Update nnbd_migration README with more details.
* 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:
parent
e62b89c56d
commit
6ac9749546
|
@ -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
|
||||
|
||||
|
|
Loading…
Reference in a new issue