Do we need to ship the null safety migration tool in Dart 3.0?

[srawlins]

This issue forks from #49529 (comment).

Currently, we have an assumption that we will continue to ship the null safety dart migrate migration tool with Dart 3.0. There may be complexities and costs to shipping such a tool in Dart 3.0, and I'm questioning strongly whether it is the correct recommendation for our users.

If the tools which ship with Dart 3.0 (VM, dart2js, IDE tooling, dart analyze, ...) will have zero support for pre-null safe code, what is the upgrade path we will recommend for users with pre-null safe code? Here are two ideas:

1. Recommend installing Dart 3.0, which continues to provide the null safety dart migrate migration tool. This tool will be able to understand pre-null safe code, and will be able to migrate it as well as it does today.

   On this path, after installing Dart 3.0, users will only have one tool which can do anything with their pre-null safe code: dart migrate. They cannot read their code in the IDE (pre-null safe code will be full of errors, as the IDE tooling will parse the code as null safe). They cannot run their tests. They cannot launch their apps. Their hands are tied until they migrate every single library to null safety (manually, or with the migration tool).

   On this path, while running the interactive migration tool, users cannot open up their code in an IDE, perhaps in order to tweak the code as it is read by the migration tool, perhaps to attempt to jump around their code. "What values are passed to this function? I'll try Go to References." Users cannot migrate one-or-a-few libraries at a time, because they cannot run tests, or their apps, until the last library is migrated.

2. Recommend installing Dart 2.19, which is the last release to provide the null safety dart migrate migration tool, then migrate all code to null safety, then install Dart 3.0.

   With Dart 2.19 installed, users can open their pre-null safe code in an IDE, they can run tests, and they can run their apps. They can inspect their code in their IDE as they use the interactive migration tool. They can migrate one-or-a-few libraries at a time, and run tests, and run their apps, and submit non-broken code in between successive iterations of the migration tool.

I think we should be consciously aware of the experience we are recommending. Then we can evaluate how to provide dart migrate in Dart 3.0, or evaluate its removal, accordingly.

[srawlins]

CC @leafpetersen @bwilkerson @jacob314 @mit-mit @vsmenon

[Cat-sushi]

I bet #2.
My understanding is that major updates are not for supporting big features but for dropping big compatiblity features.

[mit-mit]

Yes, I think #2. If you havn't migrated to null safety yet, or if you have a dependency on any of the breaking changes made between 2.12-2.19, then resolve that with the 2.19 release first (i.e. get error and warning free on 2.19).

[lrhn]

I'd prefer #1.

Someone coming back to Dart after a while downloads the newest SDK. Their code doesn't work. They look for help on the net and try dart migrate. That also doesn't work. (But it does probably recommend downloading Dart 2.19 in order to migrate code from before 2.12.)

I can see how it could be a problem to support older code. The migrate tool is probably based on the analyzer, which means it will include a pre-3.0 analyzer, a pre-3.0 SDK library, etc. We have to keep a big chunk of pre-3.0 code alive, just for the migration tool.

Is there some way we can provide a stand-alone "migrate-to-3.0" tool that you can download and use without downloading the Dart 2.19 SDK? (I don't know if you can have multiple SDK versions installed at the same time, and if not, downgrading to 2.19 every time you find an old project you want to migrate gets old very fast.)

[srawlins]

Someone coming back to Dart after a while downloads the newest SDK. Their code doesn't work.

... downgrading to 2.19 every time you find an old project you want to migrate gets old very fast.

A dependent question may be: do we keep the migration tool until 4.0? Or Some 3.x? If we remove it in some 3.x, then the problems above arise at 3.x rather than 3.0, but they arise just the same.

I can see how it could be a problem to support older code.

We might just ship a snapshot or something of the dart migrate binary which knows about 2.19 SDK and pre-null safe code. This might mean there is little cost to continuing to ship the tool for another few years.

[mit-mit]

I can't find the issue, but I seem to recall @bwilkerson mentioned that for dart fix there is a similar issue that it won't work in Dart 3 in terms of fixing issues with types that have gone from being deprecated to being removed?

[leafpetersen]

I have a fairly strong feeling that the answer for Dart 3.1 is "no, sorry, install a previous SDK" (or at least Dart 3.n for small n). I'm a little on the fence about what to do with Dart 3.0. I think the friendliest thing is to support if for one release: if you hear about all the excitement about Dart 3.0 and then go download it, it's nice if you don't have to immediately downgrade, migrate, then upgrade again. But it may not be worth it if this is a lot of effort.

A good alternative might be if we could instead of saying "go downgrade to Dart 2.19 and start over", we could just say "go download this standalone tool/package" and run that?

[srawlins]

I'm honestly not worried about how we deliver dart migrate in Dart 3.0, if that's what we want. I raised this issue more for the points about the developer experience using dart migrate with a Dart SDK for which your pre-null safe code is completely unreadable.

So even if we provide dart migrate in Dart 3.0, maybe you hear all of the excitement, you go download Dart 3.0, then see that your IDE can't read your code anymore, your tests don't run, etc. When you try to migrate, the experience is so confusing and unsound and unsettling, that you are really better off installing Dart 2.19 anyway, in order to sanely migrate your code with confidence.

[athomas]

Could we ship the migration tool via pub.dev instead? No more dart migrate, but instead you dart pub global activate migration_tool.

[bwilkerson]

My understanding is that if we were to ship the migration tool via pub.dev, it would be the same version of the tool that was shipped with the last release before 3.0 (so the user could get the same tool by installing the previous release).

Sam's point, though, is that if the user doesn't have a 3.0 release installed they won't be able to use any tool other than the migration tool during the migration, and that would make migration incredibly difficult. I don't see how the user benefits from that scenario.

[jonasfj]

This probably affects pub features such as:

• dart pub outdated --mode=null-safety
• dart pub upgrade --null-safety

These are not particularly useful in Dart 3.0; and dart pub upgrade --null-safety is probably better replaced with a dart pub upgrade --dart3 or even just dart pub upgrade --major-versions (since those are probably the same thing).

[mit-mit]

We discussed this in todays language meeting, and signed off on not supporting null safety migration with Dart 3.0 (and thus requiring using Dart 2.19 for any remaining few migrations).

Are we going to re-purpose this bug to track the implementation of this, or use a new issue for that?

[srawlins]

I'm happy to use this bug as the "remove dart migrate" issue.

[mit-mit]

Did we land all the changes for this @srawlins ?

[srawlins]

I'll let @stereotype441 decide if this should be closed or not. dart migrate is removed, but pkg/nnbd_migration is not. To be done in a follow-up CL, with coordination with google3 and @bwilkerson on an (almost) unrelated change.

[stereotype441]

I don't have much to add beyond what @srawlins said. I would prefer to leave this issue open until pkg/nnbd_migration has been removed, and I'll be happy to close it once that happens.

[mit-mit]

sgtm

[stereotype441]

After some further internal discussion we've decided to leave pkg/nnbd_migration in the open source SDK until it's no longer needed internally within Google (this will reduce the risk of us accidentally making a change that breaks migration support for internal users who haven't yet migrated).

Since support for dart migrate has already been removed, there is no further work that needs to be done, so I'm closing this issue.

[evanca]

For anyone here looking for a workaround for their super old project, you can use puro which worked really well for me:

1. Install Puro
2. Create Flutter 3.7.12 env

puro create my_env 3.7.12
puro use my_env

3. Continue migration as you would on Dart 2.19, prepending "puro" to every command, e.g.

puro dart pub outdated --mode=null-safety

4. Delete env (optional)

puro rm my_env
puro gc

Based on this answer on StackOverflow

[oti-adjei]

For anyone here looking for a workaround for their super old project, you can use puro which worked really well for me:

1. Install Puro
2. Create Flutter 3.7.12 env

puro create my_env 3.7.12
puro use my_env

3. Continue migration as you would on Dart 2.19, prepending "puro" to every command, e.g.

puro dart pub outdated --mode=null-safety

4. Delete env (optional)

puro rm my_env
puro gc

Based on this answer on StackOverflow

This also worked for me. Note though that when installing Puro,

1. Remember to add the bin directory to your PATH. Mine for example:

export PATH="$PATH:/Users/adjei/.puro/envs/my_env/flutter/bin"

where my_env is the name I gave my environment and adjei is my username
2. Append "puro" to all normal flutter/dart terminal processes so it uses the puro environment version you created instead of your existing flutter version. Examples are:

puro flutter pub get
puro dart pub upgrade --null-safety
puro dart migrate