Skip to content

[Android] Add Flutter 3.50 breaking-change page for minimum build tool versions - #14090

Open
reidbaker-agent wants to merge 5 commits into
flutter:mainfrom
reidbaker-agent:android-3.50-build-tool-minimum-versions
Open

reidbaker-agent wants to merge 5 commits into
flutter:mainfrom
reidbaker-agent:android-3.50-build-tool-minimum-versions

Conversation

@reidbaker-agent

@reidbaker-agent reidbaker-agent commented Nov 16, 2026 •

Copy link
Copy Markdown

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:

  • Documents the Flutter 3.50 minimums: AGP 9.1.1 (up from 8.11.1),
    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+.
  • Summarizes what projects need to do across projects already meeting the
    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.
  • Provides copyable before/after snippets for settings.gradle.kts
    plugins {} blocks and gradle-wrapper.properties, plus guidance on
    android.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, AGP 9.0.1–9.1.0, Gradle 9.1.0–9.3.0, and KGP 2.3.20–2.4.9 fail 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

  • If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.
  • If this PR is not meant to land until a future stable release, mark it as draft with an explanation.
  • This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).
  • This PR uses semantic line breaks
    of 80 characters or fewer.

@reidbaker
reidbaker requested a review from jesswrd November 17, 2026 17:17
Comment on lines +53 to +59
| 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]) |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using a table is a bad way to give this information. Try again.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +240 to +245
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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can remove this section I dont think we need instructions from a version that old.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Comment on lines +278 to +279
Test each configuration with `android.builtInKotlin=false` and
`android.builtInKotlin=true` in `example/android/gradle.properties`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I need @jesswrd to confirm these instructions are correct.

@reidbaker
reidbaker marked this pull request as ready for review November 17, 2026 20:08
@reidbaker
reidbaker requested review from a team and sfshaza2 as code owners November 17, 2026 20:08
@reidbaker

Copy link
Copy Markdown
Member

/gcbrun

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +36 to +39
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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
  1. 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)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +242 to +243
Unlike unpinned `plugins {}` declarations, FGP checks `ext.kotlin_version`
directly and fails validation below `2.4.10`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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
  1. 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)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the pre-Flutter 3.16 ext.kotlin_version section and snippets across the page in 9e31c5d.

@flutter-website-bot

Copy link
Copy Markdown
Collaborator

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants