[AGP 9.1.0 Migration #1] Add Android Gradle Plugin Public API migration documentation by reidbaker-agent · Pull Request #190842 · flutter/flutter

reidbaker-agent · 2026-08-10T14:56:27Z

There are 2 files in this pr. One is a document the ai used to keep track of work. More importantly it acts kind of like issues so it references the items in future prs. The second is user facing website documentation. I do not know if we will use it verbatim but for the set of prs lets treat that md doc as human understandable documentation that we must understand before landing the next pr.

Reviewers: When the pr is out of draft and your comments are fully addressed please prioritize this pr over other work. The review bar is higher, the number of reviews has more people and the work for the next pr is already done.

@reidbaker

Standard review context for this pr stack

This is PR is part of an 11 pr stack to migrate the "newdsl" gradle-api specifically in agp 9.1.0.
The complete stack has pass pre submits, post submits and customer tests. https://flutter-dashboard.appspot.com/#/build?repo=flutter&branch=experimental/agp-gradle-api

All of the code was LLM authored. A mix of manual prompting, automatic prompting, several models and adversarial review. The combined sessions are enough that I cannot include relevant prompts like I have been doing on other prs.

If you want to review the pr stack you can find it here. These prs will be abandoned/closed as prs land into flutter/flutter.

Add AGP public-API migration docs (contributor doc + breaking-change page draft) reidbaker-agent/flutter#1 (branch: agp-api-doc)
Remove AGP-internal imports from VersionFetcher and migrate compileSdk/ndk reads to the public DSL reidbaker-agent/flutter#2 (branch: agp-internal-utils)
Add public buildModeFor overloads and wire Flutter dependencies through the new DSL reidbaker-agent/flutter#3 (branch: agp-buildmode-deps)
Replace the plugin build-type copy with initWith on the public DSL reidbaker-agent/flutter#4 (branch: agp-plugin-buildtypes)
Delete getLegacyAndroidExtension and migrate the NDK fallback to the public DSL reidbaker-agent/flutter#5 (branch: agp-ndk-fallback)
Register the Flutter compile task lazily from the variant API for app projects reidbaker-agent/flutter#6 (branch: agp-assets-onvariants)
Migrate the flutter-apk copy and per-ABI versionCode to the variant API reidbaker-agent/flutter#7 (branch: agp-apk-copy-versioncode)
Unify add-to-app module wiring on the variant API and drop host-project cross-wiring reidbaker-agent/flutter#8 (branch: agp-add-to-app)
Move aar_init_script off legacy AGP APIs reidbaker-agent/flutter#9 (branch: agp-aar-script)
Flip the newDsl default: drop the opt-out from templates and migrate it away reidbaker-agent/flutter#10 (branch: agp-newdsl-flip)
Compile the Flutter Gradle Plugin against the gradle-api artifact only reidbaker-agent/flutter#11 (branch: agp-gradle-api)

Follow up work is tracked in #190964

This work is urgent in the sense that we are worried that android will publish agp 10 with no opt out but not so urgent that we are willing to break flutter users because we didn't review or understand the code because we were in a rush.

Breaking changes are expected as part of this work. There are patterns the android team explicitly does not want apps to use and apis that have no equivalent.

As part of the effort to ensure this work does not slip into ai slop, prs from this stack will be reviewed by me (@reidbaker) before asking for review. Then we will have 2 android expert reviewers also review the every pr.

Agent authored pr description
This is PR 1 of 11 in the AGP 9.1.0 / public gradle-api migration stack.

It adds the contributor-facing and website draft documentation for the Flutter Gradle Plugin's migration to the Android Gradle Plugin public Variant API, which unblocks building Flutter Android apps with AGP's newDsl=true enabled.

Part of #180137 and #166550.

Pre-launch Checklist

…page draft) Phase P0 of the Flutter Gradle Plugin migration to the AGP public API surface (flutter#180137, flutter#166550): the contributor migration record (replacement map, decision records, phase map, revert-window table) and the draft of the user-facing breaking-change page to be published to docs.flutter.dev before the newDsl flip reaches beta. Revert-safe: always.

gemini-code-assist

Code Review

This pull request introduces documentation regarding the migration of the Flutter Gradle Plugin to the public Android Gradle Plugin (AGP) API, including a contributor-facing migration record and a draft breaking-change page for users. The review feedback suggests resolving a placeholder TODO link, simplifying the onVariants API usage, using the fully qualified name for FilterConfiguration in code snippets, and safely retrieving property values using orNull instead of get().

gemini-code-assist

Code Review

This pull request introduces documentation regarding the migration of the Flutter Gradle Plugin to the public Android Gradle Plugin (AGP) API surface, including a contributor-facing record and a draft website page for user-facing breaking changes. Feedback on the draft website page highlights a Gradle anti-pattern where a provider is eagerly resolved during configuration time, and points out a potential file-overwrite issue when renaming split APKs to a hardcoded filename.

…erwrite in custom copy snippet

gemini-code-assist

Code Review

This pull request introduces documentation regarding the migration of the Flutter Gradle Plugin to the AGP public API surface, including a contributor-facing guide and a draft breaking-change page. Feedback was provided on the draft page to correct a Gradle task configuration example, as eagerly calling tasks.named inside onVariants will fail with an UnknownTaskException before the tasks are registered.

mboetger

Oof this is going to be a doozy.

mboetger · 2026-08-11T16:24:36Z

+  (`com.android.build.gradle.internal.utils.getKotlinAndroidPluginVersion` in
+  `VersionFetcher.kt`);
+- drives `flutter build aar` with legacy dynamic Groovy in
+  `aar_init_script.gradle`.


Is the plan to update this as we knock out the issues?

No, the "Today the FGP" section was point-in-time historical record of the architecture before the migration began. It will not be updated by future PRs in the stack, as its purpose is to document the original motivations and state of the world that necessitated this migration.

This document will likely be deleted at the end of the pr stack and the user facing document will also be deleted after being turned into a website pr.

My agents that worked on this were constrained to be self contained until we could prove that they could do the migration.

mboetger · 2026-08-11T16:26:59Z

+  `aar_init_script.gradle`.
+
+Flutter templates pin AGP 9.1.0 but ship `android.newDsl=false`, and a tool
+migrator (`disable_new_dsl_migration.dart`) adds the opt-out to existing


Does the developer need to run this or does the tool run this? If the tool does, when does it run.

I believe this follows the standard flutter migrator pattern and is run automatically. I think this works happens in pr 9 and we can review the implementation in that pr.

mboetger · 2026-08-11T16:38:53Z

+- Templates no longer ship `android.newDsl=false`.
+- The opt-out **add** migrator is replaced by a **removal** migrator that
+  deletes only the Flutter-added opt-out lines.
+- A fresh `flutter create` app builds with newDsl on.


Can we add something for add-to-app?

Reasonable suggestion but updating the tracking plan here wont do anything because the work is already done.
Add-to-App support was part of the requirements and I think PR 7 (branch: agp-add-to-app) handles the add to app related migrations.

mboetger · 2026-08-11T16:40:34Z

+| --- | --- | --- | --- |
+| P0 | `agp-api-doc` | S | this doc + website page draft |
+| P1 | `agp-internal-utils` | S | VersionFetcher internal util removal; numeric compileSdk compare; ndkVersion via wrapper |
+| P2 | `agp-buildmode-deps` | M | `buildModeFor` overloads; new-DSL flutter dependencies; 9.x compile axis |


Can we add a test with the bytecode check?

Similar to https://github.com/flutter/flutter/pull/190842/changes#r3760891828 modifying the plan here doesnt changet the future work. BUT I think this is done as part of PR 3 (Branch: agp-buildmode-deps) See https://github.com/reidbaker-agent/flutter/blob/837330296239879ec44631adfde3c1978c5bdc6d/packages/flutter_tools/gradle/build.gradle.kts#L86

gmackall

this lgtm, assuming we are planning to remove the work log doc when the migration is done.

separately (unrelated to this pr) it would be nice to divide docs/platforms/android in to developer/user facing docs, and contributor facing docs. It's currently a mix, which is confusing.

reidbaker · 2026-08-11T22:44:02Z

Confirming in writing that we will remove the work log document at the end of the chain. I will go ahead and file an issue for PR 12. #190964

…#12453) Manual roll Flutter from 27b098811f3b to c2437523d308 (179 revisions) Manual roll requested by tarrinneal@google.com flutter/flutter@27b0988...c243752 2026-08-12 matt.boetger@gmail.com Enable Gradle CI cache on all test targets that require android_sdk (flutter/flutter#190723) 2026-08-12 bkonyi@google.com [analysis] Reland "Added initial implementation of the flutter_analyzer_plugin (#175679)" (flutter/flutter#191022) 2026-08-12 matt.boetger@gmail.com Switch testing to gradle bin distribution type instead of all (flutter/flutter#190738) 2026-08-12 matt.boetger@gmail.com Convert Mockito instances in Kotlin to Mockk (flutter/flutter#189884) 2026-08-12 chingjun@google.com Report individual test results to LUCI ResultDB (flutter/flutter#190254) 2026-08-12 victorsanniay@gmail.com Toggleable reaction duration respects overrides (flutter/flutter#190857) 2026-08-12 engine-flutter-autoroll@skia.org Roll Skia from e00dbd7448c4 to fee7272f5bc2 (1 revision) (flutter/flutter#191007) 2026-08-12 30870216+gaaclarke@users.noreply.github.com Started caching text shadows by content. (flutter/flutter#190681) 2026-08-12 30870216+gaaclarke@users.noreply.github.com Adds agent skill for spawning led tasks. (flutter/flutter#190937) 2026-08-12 engine-flutter-autoroll@skia.org Roll Packages from aaaf246 to 94485f1 (8 revisions) (flutter/flutter#191008) 2026-08-12 82978131+herdiyana256@users.noreply.github.com flutter_tools: validate plugin identifiers before generating registrant code (flutter/flutter#190462) 2026-08-12 engine-flutter-autoroll@skia.org Roll Skia from 112f36148949 to e00dbd7448c4 (3 revisions) (flutter/flutter#190993) 2026-08-12 engine-flutter-autoroll@skia.org Roll Skia from 7d366c802307 to 112f36148949 (3 revisions) (flutter/flutter#190983) 2026-08-12 okorohelijah@google.com remove bringup for flavors test (flutter/flutter#190940) 2026-08-12 engine-flutter-autoroll@skia.org Roll Skia from 1f10a20bdd61 to 7d366c802307 (2 revisions) (flutter/flutter#190980) 2026-08-12 116356835+AbdeMohlbi@users.noreply.github.com Remove `--no-sim-use-hardfp` flag (flutter/flutter#190790) 2026-08-12 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#190977) 2026-08-12 engine-flutter-autoroll@skia.org Roll Skia from 339bedab6766 to 1f10a20bdd61 (1 revision) (flutter/flutter#190975) 2026-08-12 victorsanniay@gmail.com RawTooltip respects AnimationStyle updates and reverseCurve (flutter/flutter#190889) 2026-08-12 chris@bracken.jp ci: Support --target_arch option in prepare_package.dart (flutter/flutter#190960) 2026-08-12 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from SFq4FVodIOQAS26Lr... to -uHuSGv3wt7QAlDwa... (flutter/flutter#190973) 2026-08-12 aam@google.com Removes building of ci/android_debug_x86 as nobody should be consuming it. (flutter/flutter#190951) 2026-08-12 30870216+gaaclarke@users.noreply.github.com Adds error about wimp_heavy not being implemented. (flutter/flutter#189945) 2026-08-11 robert.ancell@canonical.com Add clang, cmake, and ninja deps to Linux windowing_test (flutter/flutter#190119) 2026-08-11 269567208+reidbaker-agent@users.noreply.github.com [AGP 9.1.0 Migration #1] Add Android Gradle Plugin Public API migration documentation (flutter/flutter#190842) 2026-08-11 bkonyi@google.com [flutter_tools] Fix deadlock in debug adapters when process exits early (flutter/flutter#190931) 2026-08-11 bkonyi@google.com [tool] Define modular dependency injection containers and bootstrapper (flutter/flutter#190724) 2026-08-11 1961493+harryterkelsen@users.noreply.github.com [web] Unify MaskFilter and ColorFilter primitives across CanvasKit and Skwasm (flutter/flutter#190314) 2026-08-11 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#190958) 2026-08-11 33794642+FelixMittermeier@users.noreply.github.com [Impeller] Move image upload scheduling waits to GPU disable (flutter/flutter#190445) 2026-08-11 30870216+gaaclarke@users.noreply.github.com Started generating the windows platform for macrobenchmarks (flutter/flutter#190932) 2026-08-11 1961493+harryterkelsen@users.noreply.github.com [web] Unify ui.Vertices (flutter/flutter#190563) 2026-08-11 jhy03261997@gmail.com Fix accessibility_inspector service extensions map mutability (flutter/flutter#190888) 2026-08-11 47866232+chunhtai@users.noreply.github.com Add batch3 a11y_assessment for vpat (flutter/flutter#189042) 2026-08-11 15619084+vashworth@users.noreply.github.com Remove Xcode environment when building swift tools in Xcode pre-action (flutter/flutter#190848) 2026-08-11 mdebbar@google.com [tool] Add missing play element in web test index.html to fix warning (flutter/flutter#190675) 2026-08-11 kkmk1999@gmail.com Offload blocking work in ProcessTextPlugin to the background (flutter/flutter#189823) 2026-08-11 bkonyi@google.com [flutter_tools] Replace usages of package:dds/dap.dart with package:dap_adapters/dap_adapters.dart (flutter/flutter#190667) 2026-08-11 15619084+vashworth@users.noreply.github.com Always update swift package dependencies (flutter/flutter#190886) 2026-08-11 bkonyi@google.com [flutter_tools] Add --preset option to flutter test (flutter/flutter#190878) 2026-08-11 jmccandless@google.com Include the examples cross imports checker in the analzyer. (flutter/flutter#190674) 2026-08-11 bkonyi@google.com [devicelab] Remove orphaned screenshot test files (flutter/flutter#190879) 2026-08-11 jason-simmons@users.noreply.github.com Remove the bringup flag from the linux_arm_host_desktop_engine builder (flutter/flutter#190935) 2026-08-11 mdebbar@google.com Reduce web_skwasm_tests subshards from 8 to 2 (flutter/flutter#190728) ...

github-actions Bot added the d: docs/ flutter/flutter/docs, for contributors label Aug 10, 2026

gemini-code-assist Bot reviewed Aug 10, 2026

View reviewed changes

reidbaker requested review from gmackall, mboetger and reidbaker August 10, 2026 15:01

reidbaker marked this pull request as draft August 10, 2026 15:12

reidbaker requested a review from jesswrd August 10, 2026 15:15

Link built-in Kotlin tracking issue flutter#184836

ddd259c

reidbaker reviewed Aug 10, 2026

View reviewed changes

Address review comments (Docs expansion, property getter fixes, clarity)

cf99f79

reidbaker reviewed Aug 10, 2026

View reviewed changes

Comment thread docs/platforms/android/website-page-draft.md Outdated

flutter deleted a comment from reidbaker-agent Aug 10, 2026

Update AGP floor section to reflect landed PRs

d799b7b

reidbaker marked this pull request as ready for review August 10, 2026 16:43

reidbaker added the CICD Run CI/CD label Aug 10, 2026

reidbaker self-requested a review August 10, 2026 16:43

gemini-code-assist Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread docs/platforms/android/website-page-draft.md Outdated

Fix trailing whitespace in markdown files

c50e6c2

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 10, 2026

reidbaker added the CICD Run CI/CD label Aug 10, 2026

reidbaker marked this pull request as draft August 10, 2026 17:52

Apply AI suggestion to fix eager Provider evaluation and split APK ov…

2a57ed9

…erwrite in custom copy snippet

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 10, 2026

reidbaker added the CICD Run CI/CD label Aug 10, 2026

reidbaker marked this pull request as ready for review August 10, 2026 18:55

gemini-code-assist Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread docs/platforms/android/website-page-draft.md

Resolve UnknownTaskException in onVariants copy snippet

0997b5a

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 10, 2026

reidbaker added the CICD Run CI/CD label Aug 10, 2026

reidbaker previously approved these changes Aug 10, 2026

View reviewed changes

Piinks added the team-android Owned by Android platform team label Aug 10, 2026

mboetger previously approved these changes Aug 11, 2026

View reviewed changes

reidbaker dismissed stale reviews from mboetger and themself via 6ddba0f August 11, 2026 18:55

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 11, 2026

github-actions Bot removed the team-android Owned by Android platform team label Aug 11, 2026

reidbaker force-pushed the agp-api-doc branch from 6ddba0f to 0997b5a Compare August 11, 2026 18:57

Fix grammar nit

40d0968

reidbaker requested a review from mboetger August 11, 2026 20:06

reidbaker approved these changes Aug 11, 2026

View reviewed changes

reidbaker changed the title ~~[AGP 9.1.0 Migration] Add Android Gradle Plugin Public API migration documentation~~ [AGP 9.1.0 Migration #1] Add Android Gradle Plugin Public API migration documentation Aug 11, 2026

gmackall approved these changes Aug 11, 2026

View reviewed changes

reidbaker added the CICD Run CI/CD label Aug 11, 2026

mboetger approved these changes Aug 11, 2026

View reviewed changes

reidbaker added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 11, 2026

auto-submit Bot added this pull request to the merge queue Aug 11, 2026

Merged via the queue into flutter:master with commit 88fe7f2 Aug 12, 2026
30 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Aug 12, 2026

Conversation

reidbaker-agent commented Aug 10, 2026 • edited by reidbaker Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

mboetger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gmackall left a comment

Choose a reason for hiding this comment

Uh oh!

reidbaker commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

reidbaker-agent commented Aug 10, 2026 •

edited by reidbaker

Loading

reidbaker commented Aug 11, 2026 •

edited

Loading