Added Docs for AGP 9

src/content/release/breaking-changes/index.md

@@ -42,6 +42,7 @@ They're sorted by release and listed in alphabetical order:
 * [`FontWeight` also controls the weight attribute of variable fonts][]
 * [Deprecate `TextField.canRequestFocus`][]
 * [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors][]
+* [Migrating Flutter Android app to Android Gradle Plugin 9.0.0][]
 * [Material 3 tokens update][]
 
 [Merged threads on Linux]: /release/breaking-changes/linux-merged-threads
@@ -50,6 +51,7 @@ They're sorted by release and listed in alphabetical order:
 [`FontWeight` also controls the weight attribute of variable fonts]: /release/breaking-changes/font-weight-variation
 [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus
 [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback
+[Migrating Flutter Android app to Android Gradle Plugin 9.0.0]: /release/breaking-changes/migrate-to-agp-9
 [Material 3 tokens update]: /release/breaking-changes/material-color-utilities
 
 <a id="released-in-flutter-338" aria-hidden="true"></a>

src/content/release/breaking-changes/migrate-to-agp-9.md

@@ -0,0 +1,153 @@
+---
+title: Migrating Flutter Android app to Android Gradle Plugin 9.0.0
+description: >-
+  How to migrate your Flutter app's Android Gradle files 
+  to build apps with Android Gradle Plugin 9.0.0+.
+---
+
+## Summary
+
+To build a Flutter app for Android, the Android Gradle Plugin (AGP)
+must be applied. As of AGP 9.0.0,
+the following migrations are required to successfully apply AGP 9+.
+
+First, built-in Kotlin is the new default, meaning any apps
+using the `kotlin-android` plugin will not build successfully.
+You must migrate from `kotlin-android` to built-in Kotlin.
+
+Second, AGP 9+ will only use the new AGP DSL interfaces.
+This means any old DSL types will not be properly read. 
+The Flutter team is working on migrating old DSL types 
+to use the new DSL. In the meantime, you can set a gradle property flag 
+to use the old DSL.
+
+In a future Flutter release, support will be added for applying AGP 9+. 
+For now, all projects must be migrated manually.
+
+To learn more about Android Gradle Plugin,
+see the [Android Gradle Plugin docs][AGP block].
+
+## Migrate
+
+These instructions assume you are updating from 
+an AGP version created before 9.0.0 to an AGP version 9.0.0+.
+You should also use the minimum compatible dependency versions
+listed in the [Android Gradle Plugin docs][AGP block].
+
+### Update the Gradle file
+
+If your app doesn't apply 
+the `kotlin-android` plugin (also called Kotlin Gradle Plugin), 
+then skip to the next step.
+
+First, find the `kotlin-android` plugin, likely located 
+in the `plugins` block of the `<app-src>/android/build.gradle` 
+or `<app-src>/android/build.gradle.kts` file.
+As an example, consider the `build.gradle.kts` file from
+a Flutter app created before this change:
+
+**Before**:
+```kotlin
+plugins {
+    id("com.android.application")
+    id("kotlin-android")
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+    ...
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_17.toString()
+    }
+    ...
+}
+...
+```
+
+Next, remove the `kotlin-android` plugin and the `kotlinOptions` block:
+
+```kotlin diff
+plugins {
+    id("com.android.application")
+    -id("kotlin-android")
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+    ...
+    -kotlinOptions {
+        -jvmTarget = JavaVersion.VERSION_17.toString()
+    -}
+    ...
+}
+```
+
+Replace the `kotlinOptions` block with the following:
+
+```kotlin diff
++kotlin {
+    +compilerOptions {
+        +jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+    +}
++}
+```
+
+Here is how the file will likely end up:
+
+**After**:
+```kotlin
+plugins {
+    id("com.android.application")
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+    ...
+    kotlin {
+        compilerOptions {
+            jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+        }
+    }
+    ...
+}
+...
+```
+
+### Set the Gradle property flag
+
+Next, to use the old AGP DSL, set the gradle property flag
+`android.newDsl` to `false` in 
+your app's `<app-src>/android/gradle.properties` file.
+
+```properties diff
+org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
+android.useAndroidX=true
++ android.newDsl=false
+```
+
+### Validate
+
+Execute `flutter run` to confirm that your app builds and
+launches on a connected Android device or emulator.
+
+## Timeline
+
+In stable release: TBD
+
+## References
+
+Relevant issue:
+[Issue #175688][]: Audit flutter for compatibility with the AGP 9.0.0
+
+The Gradle build files in your app vary based on the Flutter version 
+used when your app was created. 
+Consider staying up-to-date with the latest version 
+of the build files by periodically running `flutter upgrade` 
+in your app's directory.
+
+[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin
+
+[Issue #175688]: {{site.github}}/flutter/flutter/issues/175688