[Android] Add Java/AGP/Gradle incompatibility warning to `flutter cre…

…ate` (#131444)

Adds warning to `flutter create` command that checks if detected Java version is compatible with the template AGP and template Gradle versions. If a developer is building for Android and their Java version is incompatible with either the AGP or Gradle versions that Flutter currently supports by default for new Flutter projects, then

- a warning will show noting the incompatibility and
- steps will be shown to fix the issue, the recommended option being to configure a new compatible Java version given that Flutter knows we can support the template Gradle/AGP versions and updating them manually may be risky (feedback on this approach would be greatly appreciated!)

Given that the template AGP and Gradle versions are compatible, this PR assumes that the detected Java version may only conflict with one of the template AGP or Gradle versions because:
 - the minimum Java version for a given AGP version is less than the maximum Java version compatible for the minimum Gradle version required for that AGP version (too low a Java version will fail AGP compatibility test, but not Gradle compatibility).
- the maximum Java version compatible with minimum Gradle version for a given AGP version is higher than minimum Java version required for that AGP version (too high a Java version will fail Gradle compatibility test, but not AGP compatibility test).

Fixes #130515 in the sense that `flutter create foo`; `cd foo`; `flutter run` should always be successful.

packages/flutter_tools/lib/src/android/README.md

@@ -0,0 +1,94 @@
+# Flutter Tools for Android
+
+This section of the Flutter repository contains the command line developer tools
+for building Flutter applications on Android. What follows are some notes about
+updating this part of the tool.
+
+## Updating Android dependencies
+The Android dependencies that Flutter uses to run on Android
+include the Android NDK and SDK versions, Gradle, the Kotlin Gradle Plugin,
+and the Android Gradle Plugin (AGP). The template versions of these
+dependencies can be found in [gradle_utils.dart](gradle_utils.dart).
+
+Follow the guides below when*...
+
+### Updating the template version of...
+
+#### The Android SDK & NDK
+All of the Android SDK/NDK versions noted in `gradle_utils.dart`
+(`compileSdkVersion`, `minSdkVersion`, `targetSdkVersion`, `ndkVersion`)
+versions should match the values in Flutter Gradle Plugin (`FlutterExtension`),
+so updating any of these versions also requires an update in
+[flutter.groovy](../../../gradle/src/main/groovy/flutter.groovy).
+
+When updating the Android `compileSdkVersion`, `minSdkVersion`, or
+`targetSdkVersion`, make sure that:
+- Framework integration & benchmark tests are running with at least that SDK
+version.
+- Flutter tools tests that perform String checks with the current template
+SDK verisons are updated (you should see these fail if you do not fix them
+preemptively).
+
+#### Gradle
+When updating the Gradle version used in project templates
+(`templateDefaultGradleVersion`), make sure that:
+- Framework integration & benchmark tests are running with at least this Gradle
+version.
+- Flutter tools tests that perform String checks with the current template
+Gradle version are updated (you should see these fail if you do not fix them
+preemptively).
+
+#### The Kotlin Gradle Plugin
+When updating the Kotlin Gradle Plugin (KGP) version used in project templates
+(`templateKotlinGradlePluginVersion`), make sure that the framework integration
+& benchmark tests are running with at least this KGP version.
+
+For information aboout the latest version, check https://kotlinlang.org/docs/releases.html#release-details.
+
+#### The Android Gradle Plugin (AGP)
+When updating the Android Gradle Plugin (AGP) versions used in project templates
+(`templateAndroidGradlePluginVersion`, `templateAndroidGradlePluginVersionForModule`),
+make sure that:
+- Framework integration & benchmark tests are running with at least this AGP
+version.
+- Flutter tools tests that perform String checks with the current template
+AGP verisons are updated (you should see these fail if you do not fix them
+preemptively).
+
+### A new version becomes available for...
+
+#### Gradle
+When new versions of Gradle become available, make sure to:
+- Check if the maximum version of Gradle that we support
+(`maxKnownAndSupportedGradleVersion`) can be updated, and if so, take the
+necessary steps to ensure we are testing this version in CI.
+- Check that the Java version that is one higher than we currently support
+(`oneMajorVersionHigherJavaVersion`) based on current maximum supported
+Gradle version is up-to-date.
+- Update the `_javaGradleCompatList` that contains the Java/Gradle
+compatibility information known to the tool.
+- Update the test cases in [gradle_utils_test.dart](../../..test/general.shard/android/gradle_utils_test.dart) that test compatibility between Java and Gradle versions
+(relevant tests should fail if you do not fix them preemptively, but should also
+be marked inline).
+- Update the test cases in [create_test.dart](../../../test/commands.shard/permeable/create_test.dart) that test for a warning for Java/Gradle incompatibilities as needed
+(relevant tests should fail if you do not fix them preemptively).
+
+For more information about the latest version, check https://gradle.org/releases/.
+
+#### The Android Gradle Plugin (AGP)
+When new versions of the Android Gradle Plugin become available, make sure to:
+- Update the maximum version of AGP that we know of (`maxKnownAgpVersion`).
+- Check if the maximum version of AGP that we support
+(`maxKnownAndSupportedAgpVersion`) can be updated, and if so, take the necessary
+steps to ensure that we are testing this version in CI.
+- Update the `_javaAgpCompatList` that contains the Java/AGP compatibility
+information known to the tool.
+- Update the test cases in [gradle_utils_test.dart](../../..test/general.shard/android/gradle_utils_test.dart) that test compatibility between Java and AGP versions
+(relevant tests should fail if you do not fix them preemptively, but should also
+be marked inline).
+- Update the test cases in [create_test.dart](../../../test/commands.shard/permeable/create_test.dart) that test for a warning for Java/AGP incompatibilities as needed
+(relevant tests should fail if you do not fix them preemptively).
+
+For information about the latest version, check https://developer.android.com/studio/releases/gradle-plugin#updating-gradle.
+
+\* There is an ongoing effort to reduce these steps; see https://github.com/flutter/flutter/issues/134780.