Repository navigation
[Android] Add Flutter 3.50 breaking-change page for minimum build tool versions - #14090
reidbaker-agent wants to merge 5 commits into
Conversation
| | Project configuration | Behavior on Flutter 3.50 | Action | | ||
| | :--- | :--- | :--- | | ||
| | AGP `9.1.1` through `9.x`, Gradle `9.3.1+`, Java 17+, and built-in Kotlin (or KGP `2.4.10+`) | Passes validation; warns below AGP `9.3.1`, Gradle `9.5.0`, or KGP `2.4.20` | Optional: update to `9.3.1`, `9.5.0`, and [built-in Kotlin][] (or KGP `2.4.20`) to clear warnings | | ||
| | Unmodified Flutter 3.47 app (AGP `9.1.0`, Gradle `9.3.1`, KGP `2.4.0`) | Fails on AGP; warns on Gradle and KGP (resolved to `2.4.10`) | [Update AGP][update-agp], [Gradle][update-gradle], and [KGP][update-kgp] | | ||
| | Unmodified Flutter 3.44 app (AGP `9.0.1`, Gradle `9.1.0`, KGP `2.3.20`) | Fails on Gradle and AGP; warns on KGP (resolved to `2.4.10`) | [Update AGP][update-agp], [Gradle][update-gradle], and [KGP][update-kgp] | | ||
| | Pre-3.16 `buildscript` app (`classpath` and `ext.kotlin_version`) | Fails on any tool version below the 3.50 minimum | Update `android/build.gradle` and `gradle-wrapper.properties` ([Check your versions][check-versions]) | | ||
| | Flutter module or add-to-app project | `flutter pub get` updates standalone `.android/`; host Android apps validate host versions | Update the host Android project's Gradle, AGP, and KGP versions ([Check your versions][check-versions]) | |
There was a problem hiding this comment.
Using a table is a bad way to give this information. Try again.
There was a problem hiding this comment.
Replaced the second table in ## Summary with a short bulleted list grouped by action needed (projects meeting the minimums, Flutter apps and add-to-app host projects below the minimums, and Android plugins) in 9e31c5d.
| On projects created before Flutter 3.16, update `ext.kotlin_version` in | ||
| `android/build.gradle` instead. | ||
| Unlike unpinned `plugins {}` declarations, FGP checks `ext.kotlin_version` | ||
| directly and fails validation below `2.4.10`. | ||
|
|
||
| Code before migration: |
There was a problem hiding this comment.
We can remove this section I dont think we need instructions from a version that old.
There was a problem hiding this comment.
Removed the pre-Flutter 3.16 buildscript, classpath, and ext.kotlin_version instructions and snippets across the page in 9e31c5d.
| AGP `9.3.1` (with Gradle `9.5.0`), with `android.builtInKotlin=false` and | ||
| `android.builtInKotlin=true`. | ||
| For plugin migration details, consult the | ||
| Verify your plugin's `example/` app against both supported configurations: |
There was a problem hiding this comment.
@jesswrd do you think plugin developers need to do this? in general most plugins do not do crazy gradle things and the ones that do know how to test across gradle versions.
| Test each configuration with `android.builtInKotlin=false` and | ||
| `android.builtInKotlin=true` in `example/android/gradle.properties`. |
There was a problem hiding this comment.
@jesswrd I can see you wanting to test with this but want confirmation.
| When you're ready to adopt AGP 9's defaults: | ||
| Use the following guides when you're ready to adopt the AGP 9 defaults: | ||
|
|
||
| - To migrate to built-in Kotlin (`android.builtInKotlin=true`), follow |
There was a problem hiding this comment.
I need @jesswrd to confirm these instructions are correct.
|
/gcbrun |
There was a problem hiding this comment.
Code Review
This pull request adds a new breaking change document detailing the raised minimum Android build tool versions for Flutter 3.50, which now requires Android Gradle Plugin 9.1.1, Gradle 9.3.1, and Kotlin Gradle Plugin 2.4.10. It also updates the breaking changes index to link to this new page. The review feedback suggests clarifying the explanations of how Gradle resolves Kotlin Gradle Plugin (KGP) versions in the plugins block versus how the Flutter Gradle Plugin (FGP) directly validates ext.kotlin_version to avoid confusing developers.
| In `settings.gradle(.kts)`, Gradle resolves unpinned KGP versions up to | ||
| `2.4.10` and logs a warning. | ||
| Pinning KGP below `2.4.10`, or setting `ext.kotlin_version` below `2.4.10`, | ||
| fails validation. |
There was a problem hiding this comment.
Calling KGP versions in the plugins {} block "unpinned" is confusing to developers, as the template explicitly specifies a version (e.g., version "2.4.0"). In Gradle, these are overridden/upgraded by the buildscript classpath dependencies (like FGP), not because they are "unpinned". Clarifying this distinction makes the validation behavior much easier to understand.
Suggested change:
In `settings.gradle(.kts)`, Gradle resolves KGP versions declared in the
`plugins {}` block up to `2.4.10` and logs a warning.
Setting `ext.kotlin_version` below `2.4.10` directly in `build.gradle`
fails validation.References
- The repository style guide specifies that documentation prose follows the Google developer documentation style guide, prioritizing clarity and accuracy for readers, and that comments should include the problem, consequence, and smallest useful fix. (link)
There was a problem hiding this comment.
Updated in 9e31c5d: clarified that Gradle dependency resolution upgrades lower KGP versions in settings.gradle(.kts) plugins {} (such as 2.4.0) to 2.4.10 with a warning, and that only a strict KGP version constraint below 2.4.10 fails validation.
| Unlike unpinned `plugins {}` declarations, FGP checks `ext.kotlin_version` | ||
| directly and fails validation below `2.4.10`. |
There was a problem hiding this comment.
Clarify that the difference is due to Gradle's automatic dependency resolution upgrading the plugin version on the classpath, whereas ext.kotlin_version is read directly by FGP as a property and cannot be automatically upgraded.
Suggested change:
Unlike KGP versions declared in the `plugins {}` block (which Gradle can automatically upgrade), FGP checks `ext.kotlin_version` directly and fails validation below `2.4.10`.References
- The repository style guide specifies that documentation prose follows the Google developer documentation style guide, prioritizing clarity and accuracy for readers, and that comments should include the problem, consequence, and smallest useful fix. (link)
There was a problem hiding this comment.
Removed the pre-Flutter 3.16 ext.kotlin_version section and snippets across the page in 9e31c5d.
|
Staged preview of the updated docs.flutter.dev site (updated for commit c5187cf): https://flutter-docs-prod--docs-pr14090-android-3-50-build-too-r55mlqon.web.app |
…ts, and clarify KGP resolution
Description of what this PR is changing or adding, and why:
Adds the Flutter 3.50 Android breaking-change and migration guide
Raised minimum Android build tool versions
(
/release/breaking-changes/android-build-tool-minimum-versions,split out from #14053)
and lists the page under "Released in Flutter 3.50" in the breaking-changes
index:
Gradle 9.3.1 (up from 8.14.0), and KGP 2.4.10 when KGP is applied
(up from 2.2.20), along with the Flutter 3.50 template defaults
(AGP 9.3.1, Gradle 9.5.0, KGP 2.4.20) and the validation error rejecting
AGP 10+.
3.50 minimums, Flutter apps and add-to-app host projects below the minimums
(including unmodified apps created with Flutter 3.47 or earlier), standalone
Flutter modules, and Android plugins.
settings.gradle.ktsplugins {}blocks andgradle-wrapper.properties, plus guidance onandroid.builtInKotlin=false,android.newDsl=false, and--android-skip-build-dependency-validation.Important
Open question before marking ready for review:
Under
## Background, the page links the Android dependency versions support policy ("warn for at least one stable release before raising the minimum"). In Flutter 3.50, AGP9.0.1–9.1.0, Gradle9.1.0–9.3.0, and KGP2.3.20–2.4.9fail validation without a prior warning in Flutter 3.47. Confirm whether to keep the page focused on the 3.50 minimums as written, or add an explicit note that 3.50 made an exception to the warning-cycle policy.Companion PR for the Flutter Gradle Plugin Variant API migration guide:
#14053
Issues fixed by this PR (if any):
None.
PRs or commits this PR depends on (if any):
None.
Presubmit checklist
of 80 characters or fewer.