From ed71f924b12308e9fc8f85424da0ae90012e98da Mon Sep 17 00:00:00 2001
From: Reid Baker <reidbaker@google.com>
Date: Thu, 20 Feb 2025 17:02:56 -0500
Subject: [PATCH] Create Android-API-And-Related-Versions.md (#163556)

From
https://github.com/flutter/flutter/pull/163542#issuecomment-2666519573

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.
---
 .../Android-API-And-Related-Versions.md       | 122 ++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 docs/contributing/Android-API-And-Related-Versions.md

diff --git a/docs/contributing/Android-API-And-Related-Versions.md b/docs/contributing/Android-API-And-Related-Versions.md
new file mode 100644
index 0000000000..a1df1d46fd
--- /dev/null
+++ b/docs/contributing/Android-API-And-Related-Versions.md
@@ -0,0 +1,122 @@
+# Android Api and Related versions
+
+Picking the full suite of android versions can be difficult if you are not a full time android developer.
+This document is for contributors to understand what versions of common android tooling should be used in the flutter/flutter codebase.
+
+## Overview
+
+**The most important thing is for any test, project, or app to have compatible versions. **
+
+If versions need to be different then a comment explaining why and what is being evaluated should be included.
+All chosen versions should pass the minimum versions checks defined in [DependencyVersionChecker](https://github.com/flutter/flutter/blob/main/packages/flutter_tools/gradle/src/main/kotlin/DependencyVersionChecker.kt)
+
+If the versions chosen are not known by [gradle_utils.dart](https://github.com/flutter/flutter/blob/a16c447abcb695b4ca907d59e66dc87f4f7178d3/packages/flutter_tools/lib/src/android/gradle_utils.dart#L63) then update gradle_utils.dart.
+
+## Specifics
+
+### compileSdk
+
+- Must be higher then or equal to `targetSdk`.
+- Should be `compileSdk` instead of `compileSdkVersion`.
+- Should be the max stable value available in CIPD if not `flutter.compileSdkVersion`.
+- Must have a comment if an api level lower than max is chosen intentionally.
+
+```
+// OK
+android {
+  compileSdk flutter.compileSdkVersion
+}
+```
+
+```
+// OK if flutter.compileSdkVersion is not available like in an add to app example.
+android {
+  compileSdk 35
+}
+```
+
+```
+// NOT OK
+android {
+  compileSdk 28
+}
+```
+
+### targetSdk
+
+- Must be higher then or equal to `minSdk`.
+- Should be `targetSdk` instead of `targetSdkVersion`.
+- `targetSdk` takes human level effort to update. This is a design decision by the AGP team.
+- `targetSdk` may lag behind compile sdk because of the effort to update.
+- If the `targetSdk` version is intentionally different there should be a comment explaining why.
+
+```
+// OK
+defaultConfig {
+  targetSdk flutter.targetSdkVersion
+}
+```
+
+```
+// OK if flutter.compileSdkVersion is not available like in an add to app example.
+defaultConfig {
+  targetSdk 35
+}
+```
+
+```
+// NOT OK
+defaultConfig {
+  targetSdk 28
+}
+```
+
+### AGP
+AKA `com.android.application`, `com.android.tools.build:gradle` `com.android.library`
+
+- "AGP" version should be the version set in flutter templates or newer.
+- If the version is intentionally different there should be a comment explaining why.
+
+
+```
+// OK
+dependencies {
+    classpath "com.android.tools.build:gradle:8.8.1"
+}
+```
+
+```
+// OK
+dependencies {
+    // Testing backwards compatability of feature XYZ
+    classpath "com.android.tools.build:gradle:7.5.2"
+}
+```
+
+### gradle
+
+Gradle versions are the least likley to break across minor version updates.
+
+- In new code the "gradle" version should be the version set in flutter templates or newer.
+- In older code any gradle version that works with the other version constraints is ok.
+- In practice our customers use a large variety of gradle versions.
+- If the version is intentionally different there should be a comment explaining why.
+
+```
+// OK
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.12.1-bin.zip
+```
+
+### kotlin
+
+Changing kotlin versions is most likley to have an issue with another dependency and not the code under test.
+
+- "kotlin" version should be the version set in flutter templates or newer.
+- If the version is intentionally different there should be a comment explaining why.
+
+```
+// Ok
+ext.kotlin_version = "1.7.10"
+...
+classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+```