Successfully built examples/hello_world 🎉

Now I'm thinking what to do next:

1) All in

• We migrate all example apps, integration test apps, benchmark apps in the flutter repo to the new, declarative way of applying the Flutter Gradle Plugin.
• We also write a migration to make this transition seamless for customers.
• The "new way of applying the plugin" becomes the only way, because all the existing projects are automatically migrated.

I think it won't be a breaking change since it'll be handled automatically by the migration. So we won't have to go through this process.

2) Gradual

We migrate some example apps, integration test apps, and benchmark apps in the flutter repo to the new, declarative way of applying the Flutter Gradle Plugin.

The "new way" and the "old way" coexist.

We should write the migration anyway, IMHO.

I prefer option 1) which will require less support.

cc @gnprice @reidbaker

I am skeptical of requiring the migration for all apps even if we build a tool to do the migration. That said for code owned by flutter I think I could get behind requiring the migration.

Neat!

What would be the advantage of option 1 over option 2? What sorts of things would we be able to do because we're no longer supporting the old way, or what sorts of work would be required to continue supporting the old way?

I'd be nervous about going all at once to supporting only the new way. Doing so would mean that if for any particular project the automatic migration doesn't quite work 100% seamlessly out of the box, that project would be totally blocked on upgrading Flutter until they figure out what this transition is about well enough for them to make the migration manually.

Based on the diff in the example app, this will probably be a more complex migration than many migrations are. And the app build.gradle is a file that people regularly make manual changes to, for a variety of good and necessary reasons. So between those two factors, I think it's fairly likely that however well we write the auto-migration, there will be some projects where the file has been rearranged enough that the auto-migration isn't able to completely understand what's going on, and doesn't apply its changes.

OTOH if

• we get to something that supports both the new way and the old way;
• plus there's an auto-migration that works smoothly for most projects;
• and there's also perhaps a writeup somewhere that clearly explains what this change is about and why it's good, and how to do it manually if the auto-migration didn't work, and the auto-migration links to that when it fails to apply;

then after that's been out in a stable release for some time, if there's a clear benefit we'd get (perhaps even just cleaning up the code) from dropping support for the old way, I think dropping it would be a lot more palatable at that point.

One point of comparison is Flutter's deprecation policy:

The lifetime for a Flutter deprecation is 1 year after reaching the stable channel, or after 4 stable releases, whichever is longer.

I think that policy doesn't directly apply here; it's intended for the framework's Dart API. But as long as there's an auto-migration, I think the situation is pretty comparable, and it'd be reasonable to take the same approach.

I got both the "new" and "old" style apply of Flutter Gradle Plugin to work (so, essentially, option (2)). Doing that felt like defusing a bomb btw.

Most tests pass except for add-to-app scenarios. Gonna work on fixing them now.

Got all tests to pass.

I'd be happy to hear your opinions on the current progress.

I think the next steps are:

• write an automatic migration so that most existing projects will be updated
• update flutter create templates for the "new way" of applying the FGP (Flutter Gradle Plugin)
• deprecate the "old way" of applying the FGP and advise developers to migrate to the "new way". After ~1 year (in line with the Deprecation Policy), support for the old way would be removed.

Automatic migration

Here's an overview of what it should do:

• android/app/build.gradle file

  +plugins {
  +    id "dev.flutter.flutter-gradle-plugin"
  +}
  -apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"

  More ambitious version:

  +plugins {
  +    id "com.android.application"
  +    id "dev.flutter.flutter-gradle-plugin"
  +}
  -apply plugin: 'com.android.application'
  -apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"

  If the app uses apply for other plugins, I'd leave the migration up to the developers. It's hard/impossible to handle all the cases automatically.

• android/settings.gradle file

  I'd like to extract this common boilerplate somewhere, but haven't found a way. See here for more details. So until we find a more concise snippet, it'd look like this:

  +pluginManagement {
  +    def localPropertiesFile = new File(rootProject.projectDir, "local.properties")
  +    def properties = new Properties()
  +    assert localPropertiesFile.exists()
  +    localPropertiesFile.withReader("UTF-8") { reader -> properties.load(reader) }
  +    def flutterSdkPath = properties.getProperty("flutter.sdk")
  +    assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
  +
  +    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")
  +
  +    plugins {
  +        id "dev.flutter.flutter-gradle-plugin" version "1.0.0" apply false
  +    }
  +}

@gnprice raised some important caveats in this comment - the Gradle build files are often edited for various reasons, even more so in larger, complex projects. I tried to keep the migration as lean as possible, but I'm still afraid some edge cases might exist that'd make it hard/impossible to make it work 100% of the time (for example, add-to-app scenarios). So my question is: what should happen if the project can't be automatically migrated? How to fail gracefully in such a case?

I'm also all in for writing a short article explaining (1) why this migration is good and (2) how to do it manually, in case it cannot be done automatically.

Upgrade default templates

That should be pretty straightforward - I've already done that in #122290 and #123426.

Oof, Google testing failed. cc @reidbaker

Thanks for taking a look.

Then the template changes and the migration can go in a followup PR or two.

Actually, I'd prefer to include template changes at least in this PR. No strong opinions though.

So my question is: what should happen if the project can't be automatically migrated? How to fail gracefully in such a case?

Since the old way will continue to work (for some time, anyway), in this case the migration can just leave the files untouched and that will be safe.
Then it might also print a message, something like:

Unable to automatically upgrade Android build files to declarative form.
Consider doing the upgrade manually:
  https://docs.flutter.dev/path/to/migration/guide

The main problem is that we can't detect if the migration was successful just after we've performed it. The developer has to run Gradle build, and only after it passes/fails, we can be certain.

I'm not sure we could make this experience more seamless. The first idea off the top of my head:

1. Create some temporary file ({gradle_migration_checked: false}) just after the migration has been performed
2. The user runs flutter build apk/flutter run on Android device
3. If the build fails because of any Gradle failure, and if the gradle_migration_checked in the temporary file is false, we print your error message about the migration and automatically rollback, suggesting to migrate manually.
4. If the build succeeds, we delete the file or write true to it.

Honestly? I hate this idea :)

Another take: when the migration is performed, its logs are only printed when running with --verbose. I think this is not ideal for "larger", potentially breaking migrations, like this one. In such cases, migration logs should be always printed (no matter the --verbose flag). See relevant code.
The migration model could be extended so that individual migrations could override a new, hypothetical bool potentiallyBreaking, and if it's true, logger.printStatus() would be used instead of logger.printTrace().

EDIT: Actually I see that logger.printStatus() is used for logging that the migration is being performed. And in migrations that don't call processFileLines(), the logger.printStatus() is used anyway, e.g here.

Actually, I'd prefer to include template changes at least in this PR. No strong opinions though.

Sure, WFM.

The main problem is that we can't detect if the migration was successful just after we've performed it. The developer has to run Gradle build, and only after it passes/fails, we can be certain.

Ah. Yeah, the approach that's generally been taken in these migrations is to instead say: if we're not certain that the migration will be a success when it applies, then we make the patterns of what it's looking for in the file more specific until we are pretty much certain.

As you outline, the model for how these migrations run doesn't really allow for a great UX/DX for doing a migration that has more uncertainty like that. I think that'd call for an interaction that the user had to more explicitly trigger — along the lines of the Android Studio upgrade wizards, and that's perhaps what flutter migrate was projected to be as well (but it seems like that project didn't really get completed.)

I think it will be quite doable here to make a migration that we can be sure of in that way. It just means there'll be a significant swath of projects the auto-migration doesn't apply to; but the long tail which haven't changed much in this file from the template will still benefit.

if we're not certain that the migration will be a success when it applies, then we make the patterns of what it's looking for in the file more specific until we are pretty much certain.

We'll need a way to test the migrations on some real apps. For example, run all the migrations over apps in examples and dev and make sure nothing breaks.

It just means there'll be a significant swath of projects the auto-migration doesn't apply to

For them we could print a warning each time they flutter run/build on Android:

Your project is using the outdated, non-declarative form of applying Flutter Gradle Plugin. Support for it will be removed in a future version of Flutter.
Consider doing the upgrade manually:
  https://docs.flutter.dev/path/to/migration/guide

So to sum up todos:

• This PR: refactor FGP to support declarative apply, update template (but imho, we've got a blocker here)
• Future PR: write the laser-focused automatic migration, write the migration guide doc, print warning if using imperative apply
• Far future PR: remove support for imperative apply

I can create issues for them (or you can, if you want to) once you and @reidbaker agree on this rough plan.

PS

along the lines of the Android Studio upgrade wizards, and that's perhaps what flutter migrate was projected to be as well (but it seems like that project didn't really get completed.)

I think that a separate flutter migrate command would be great (for "larger" migrations maybe?) if the flutter tool detected that some migrations have to be run and reminded the user to do them. It'd also "raise awareness" among the developers that such automatic migrations are a thing.

We'll need a way to test the migrations on some real apps. For example, run all the migrations over apps in examples and dev and make sure nothing breaks.

Definitely. I think customer_testing, and also Google testing, will contribute here too.

There may be internal apps at Google where the overall app build doesn't get run in the presubmit "Google testing" check. In that case, once there's a draft of the migration, @reidbaker or another Googler can probably help by running the PR across those other Google-internal apps. That will confirm that the migration either succeeds, or successfully chooses not to apply itself.

So to sum up todos:

SGTM!

(but imho, we've got a blocker here)

I wouldn't consider that duplication a blocker. If the duplication is the best way to do it that we can find given how Gradle works, then that's OK.

If you have any more ideas for how to deduplicate, though, it'd make sense to try a bit more. Or if you want to wait another day to see if that Stack Overflow question gets an answer.

Oof, Google testing failed. cc @reidbaker

Hey sorry I can dig in but it will probably be a week. This impending Flamingo launch and the work associated with it is my top priority until it is handled. That said maybe another googler can take a look.

@camsim99 After your gradle error catching work would you be willing to take a look at this?

Since WHEN AND WHICH VERSION the declarative way plugins{} is added ?

I have lost a half a day figuring this out!!

Please someone mention the documentation or any useful link.

I am using Flutter 3.10

and my android studio generates this when creating a new project

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"

and my Colleague has this in their project

plugins {
    id "com.android.application"
    id "kotlin-android"
    id "dev.flutter.flutter-gradle-plugin"
}

Can somebody please tell me why my version generates apply plugin instead of plugins{}

Since WHEN AND WHICH VERSION the declarative way plugins{} is added ?

It was a gradual migration. See #135392 to see how Android build files differ between versions.

my android studio generates this when creating a new project (...) my Colleague has this in their project

Your colleague and you have different Flutter versions installed. Upgrade to the newest one to take advantage of the latest, modern-Gradle-style template.