From 6e0b09f374a0764731d447ef26ef91f757ed05ba Mon Sep 17 00:00:00 2001 From: Jeremi Kurdek <59935235+jkurdek@users.noreply.github.com> Date: Mon, 24 Feb 2025 23:52:59 +0100 Subject: [PATCH 1/5] Describe NDK upgrade process --- .../testing/libraries/testing-android.md | 31 ++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/workflow/testing/libraries/testing-android.md b/docs/workflow/testing/libraries/testing-android.md index 6322950a1fec8f..2794f3efa2ce67 100644 --- a/docs/workflow/testing/libraries/testing-android.md +++ b/docs/workflow/testing/libraries/testing-android.md @@ -22,7 +22,7 @@ Android SDK and NDK can be automatically installed via the following script: #!/usr/bin/env bash set -e -NDK_VER=r23c +NDK_VER=r27c SDK_VER=9123335_latest SDK_API_LEVEL=33 SDK_BUILD_TOOLS=33.0.1 @@ -154,3 +154,32 @@ The emulator can be launched with a variety of options. Run `emulator -help` to ### Debugging the native runtime code using Android Studio See [Debugging Android](../../debugging/mono/android-debugging.md) + +## Upgrading the Android NDK Version in CI Pipelines + +The Android NDK LTS version is released annually. CI pipelines retrieve the NDK version from Docker images hosted in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository. +For reference, see an example Dockerfile: +[Azure Linux 3.0 .NET 10.0 Android Dockerfile](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/main/src/azurelinux/3.0/net10.0/android/amd64/Dockerfile). + +To upgrade the NDK version used in CI for building and testing Android, follow these steps: + +### 1. Verify the New NDK Version Locally +- Download the new NDK version. +- Test the local build using the new NDK by building a sample Android app. +- Ensure **AOT** and **AOT_WITH_LIBRARY_FILES** are enabled in the build. + +### 2. Test the New NDK in CI +- Create a new Docker image containing the updated NDK version. +- Open a **draft PR** in the **runtime** repository that updates the Dockerfile reference to use the new image. +- Monitor CI results and fix any failures. + +### 3. Commit Changes Without Updating the Docker Reference +- Once CI is green, **commit only the necessary changes** (e.g., fixes, build adjustments) to the respective branch. +- **Do not** change the Docker image reference in the final commit. +- Merge the PR. + +### 4. Update the NDK Version in the Prerequisites Repository +- Update the NDK version in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository by modifying the Dockerfile. +- The updated NDK will automatically flow to all builds of a given branch once merged. + +By following these steps, you ensure a smooth upgrade of the Android NDK in CI while maintaining stability and compatibility. From c2aa7832367c1cc8fe351faf4028fc545dd8da04 Mon Sep 17 00:00:00 2001 From: Jeremi Kurdek Date: Mon, 24 Feb 2025 23:56:34 +0100 Subject: [PATCH 2/5] Improve documentation --- .../testing/libraries/testing-android.md | 31 +++++++++---------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/docs/workflow/testing/libraries/testing-android.md b/docs/workflow/testing/libraries/testing-android.md index 2794f3efa2ce67..35be0df390ecb7 100644 --- a/docs/workflow/testing/libraries/testing-android.md +++ b/docs/workflow/testing/libraries/testing-android.md @@ -157,29 +157,26 @@ See [Debugging Android](../../debugging/mono/android-debugging.md) ## Upgrading the Android NDK Version in CI Pipelines -The Android NDK LTS version is released annually. CI pipelines retrieve the NDK version from Docker images hosted in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository. -For reference, see an example Dockerfile: -[Azure Linux 3.0 .NET 10.0 Android Dockerfile](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/main/src/azurelinux/3.0/net10.0/android/amd64/Dockerfile). +The Android NDK LTS version is released annually. CI pipelines retrieve the NDK version from Docker images hosted in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository. +For reference, see an example Dockerfile: +[Azure Linux 3.0 .NET 10.0 Android Dockerfile](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/main/src/azurelinux/3.0/net10.0/android/amd64/Dockerfile). To upgrade the NDK version used in CI for building and testing Android, follow these steps: ### 1. Verify the New NDK Version Locally -- Download the new NDK version. -- Test the local build using the new NDK by building a sample Android app. -- Ensure **AOT** and **AOT_WITH_LIBRARY_FILES** are enabled in the build. +- Download the new NDK version. +- Test the local build using the new NDK by building a sample Android app. +- Ensure **AOT** and **AOT_WITH_LIBRARY_FILES** are enabled in the build. -### 2. Test the New NDK in CI -- Create a new Docker image containing the updated NDK version. -- Open a **draft PR** in the **runtime** repository that updates the Dockerfile reference to use the new image. -- Monitor CI results and fix any failures. - -### 3. Commit Changes Without Updating the Docker Reference -- Once CI is green, **commit only the necessary changes** (e.g., fixes, build adjustments) to the respective branch. -- **Do not** change the Docker image reference in the final commit. -- Merge the PR. +### 2. Test the New NDK in CI and Fix Issues +- Create a new Docker image containing the updated NDK version. +- Open a **draft PR** in the **runtime** repository that updates the Dockerfile reference to use the new image. +- Monitor CI results and fix any failures. +- Once CI is green, **commit only the necessary changes** (e.g., fixes, build adjustments) to the respective branch. +- **Do not** change the Docker image reference in the final commit. ### 4. Update the NDK Version in the Prerequisites Repository -- Update the NDK version in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository by modifying the Dockerfile. -- The updated NDK will automatically flow to all builds of a given branch once merged. +- Update the NDK version in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository by modifying the Dockerfile. +- The updated NDK will automatically flow to all builds of a given branch once merged. By following these steps, you ensure a smooth upgrade of the Android NDK in CI while maintaining stability and compatibility. From 0529da4f98a27a33b8e4f136033c540a0db165a5 Mon Sep 17 00:00:00 2001 From: Jeremi Kurdek Date: Mon, 24 Feb 2025 23:57:08 +0100 Subject: [PATCH 3/5] Fix numbering --- docs/workflow/testing/libraries/testing-android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/workflow/testing/libraries/testing-android.md b/docs/workflow/testing/libraries/testing-android.md index 35be0df390ecb7..848e9059aa4694 100644 --- a/docs/workflow/testing/libraries/testing-android.md +++ b/docs/workflow/testing/libraries/testing-android.md @@ -175,7 +175,7 @@ To upgrade the NDK version used in CI for building and testing Android, follow t - Once CI is green, **commit only the necessary changes** (e.g., fixes, build adjustments) to the respective branch. - **Do not** change the Docker image reference in the final commit. -### 4. Update the NDK Version in the Prerequisites Repository +### 3. Update the NDK Version in the Prerequisites Repository - Update the NDK version in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository by modifying the Dockerfile. - The updated NDK will automatically flow to all builds of a given branch once merged. From 65cdfad9bc003bd9b1ab0f3e83d5c05a8e76fdd5 Mon Sep 17 00:00:00 2001 From: Jeremi Kurdek Date: Tue, 4 Mar 2025 11:16:03 +0100 Subject: [PATCH 4/5] Add additional context requested in PR review --- docs/workflow/testing/libraries/testing-android.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/workflow/testing/libraries/testing-android.md b/docs/workflow/testing/libraries/testing-android.md index 848e9059aa4694..127f1765fe0c5d 100644 --- a/docs/workflow/testing/libraries/testing-android.md +++ b/docs/workflow/testing/libraries/testing-android.md @@ -157,9 +157,16 @@ See [Debugging Android](../../debugging/mono/android-debugging.md) ## Upgrading the Android NDK Version in CI Pipelines -The Android NDK LTS version is released annually. CI pipelines retrieve the NDK version from Docker images hosted in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository. -For reference, see an example Dockerfile: -[Azure Linux 3.0 .NET 10.0 Android Dockerfile](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/main/src/azurelinux/3.0/net10.0/android/amd64/Dockerfile). +The Android NDK has two release channels: a rolling release, which occurs approximately every quarter, and a Long Term Support (LTS) release, which happens once a year (typically in Q3). While release dates are not guaranteed, LTS versions receive support for at least one year or until the next LTS reaches the release candidate stage. After that, the NDK version stops receiving bug fixes and security updates. + +The LTS NDK release schedule roughly aligns with the .NET Release Candidate (RC) timeline. Given this, we should plan to upgrade the NDK version used in `main` around that time. If we successfully upgrade before .NET release, we can ensure that our CI builds and tests run against a supported NDK version for approximately 9 months after the release. + +.NET MAUI is supported for 18 months after each .NET release. This means the NDK version used in CI will be supported for about half the lifecycle of a given .NET MAUI release. If we want to ensure that the NDK version used in CI is supported for the entire lifecycle of a given .NET MAUI release, we should consider upgrading the NDK version in the `release` branches. + +CI pipelines retrieve the NDK version from Docker images hosted in the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository. + +For reference, see an example Dockerfile NDK definition: +[Azure Linux 3.0 .NET 10.0 Android Dockerfile](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/c480b239b3731983e36b0879f5b60d8f4ab7b945/src/azurelinux/3.0/net10.0/android/amd64/Dockerfile#L2). To upgrade the NDK version used in CI for building and testing Android, follow these steps: From 1f5d8077486cc21f2d874e84fb7e48221527daaf Mon Sep 17 00:00:00 2001 From: Jeremi Kurdek <59935235+jkurdek@users.noreply.github.com> Date: Tue, 22 Apr 2025 14:24:48 +0200 Subject: [PATCH 5/5] Improve description --- docs/workflow/testing/libraries/testing-android.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/workflow/testing/libraries/testing-android.md b/docs/workflow/testing/libraries/testing-android.md index 127f1765fe0c5d..9b138a0b61b5b1 100644 --- a/docs/workflow/testing/libraries/testing-android.md +++ b/docs/workflow/testing/libraries/testing-android.md @@ -168,6 +168,7 @@ CI pipelines retrieve the NDK version from Docker images hosted in the [dotnet-b For reference, see an example Dockerfile NDK definition: [Azure Linux 3.0 .NET 10.0 Android Dockerfile](https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/c480b239b3731983e36b0879f5b60d8f4ab7b945/src/azurelinux/3.0/net10.0/android/amd64/Dockerfile#L2). +Bumping version of the NDK in the prereqs repo will automatically propagate it to all CI runs Thus, bumping the NDK requires a three step process in order to ensure that CI continues to operate correctly. To upgrade the NDK version used in CI for building and testing Android, follow these steps: ### 1. Verify the New NDK Version Locally @@ -176,7 +177,7 @@ To upgrade the NDK version used in CI for building and testing Android, follow t - Ensure **AOT** and **AOT_WITH_LIBRARY_FILES** are enabled in the build. ### 2. Test the New NDK in CI and Fix Issues -- Create a new Docker image containing the updated NDK version. +- Create a new Docker image containing the updated NDK version (based on the original docker image from the [dotnet-buildtools-prereqs-docker](https://github.com/dotnet/dotnet-buildtools-prereqs-docker) repository). - Open a **draft PR** in the **runtime** repository that updates the Dockerfile reference to use the new image. - Monitor CI results and fix any failures. - Once CI is green, **commit only the necessary changes** (e.g., fixes, build adjustments) to the respective branch.