Android OS onboarding doc

[richlander]

Is there a doc that describes how to onboard a new Apple OS (for build or test) in this repo?

We've started writing such docs to make ourselves more efficient and make such tasks more easily repeatable.

Here are some other efforts:

• Add doc on OS onboarding #112026
• Create an OS onboarding doc aspnetcore#60281
• Source build and VMR should move to CentOS Stream 10 main source-build#4890

A new Android version is coming soon. Perhaps we use that as the forcing function and example to write a doc if one doesn't exist.

[jpobst]

I'm not sure I fully understand what information you are looking for. If it's "here's the steps we take to add a new Android API level", I perform that work and I use (and update) this guide:

https://github.com/dotnet/android/blob/main/Documentation/workflow/HowToAddNewApiLevel.md

Since it has traditionally only been done once a year (this year it will be twice), I have to maintain this document or else I will forget the steps. 😅

[richlander]

Excellent! I'll link to that doc. Can you explain the distinction between adding an API level and testing a new OS version?

[jonpryor]

@richlander asked:

Can you explain the distinction between adding an API level and testing a new OS version?

You (typically) don't need to use new APIs to run on a new OS version. (See also Backward Compatibility and running DOS apps on Windows.) It is entirely possible to write an app (in Java) against Android API-1 and run it on Android 16. (Would it be an interesting app? Probably not! But you could! You can't do the same from C# because .NET for Android uses native libraries with symbols added in API-21, so API-21 is currently our lowest supported API level.)

Testing a new OS version involves running our unit tests on a "device" (typically an emulator) running the new OS version. This doesn't require the binding or usage of new APIs.

Adding an API level means binding added APIs so that they can be used from C#. For example, Android 16 Beta 1 adds AccessibilityManager.addHighContrastTextStateChangeListener(). In order to call that method from C#:

1. The method and related parameter types must be "bound"/"projected" into C#.
2. The app calling that method must be running on Android 16 Beta 1. (Maybe not even later! The method may be gone in Beta 2; who knows!)

This should be identical to every other "reasonable" operating system in existence with a modicum of backward compatibility: running on the latest OS version (generally) doesn't require using new APIs that only exist in that OS version; rather, "testing a new OS version" just means "does my app run on that OS version?". (If the app doesn't run, this might be a good time to file a bug with the OS vendor.) Merely being able to run on the latest OS version does not mean that any APIs added in that OS version are otherwise available to your app; that may require additional work.

[richlander]

That's useful context!

The real q is what is it that we need to do to feel comfortable adding a new version to our support docs? Like: https://github.com/dotnet/core/blob/main/release-notes/9.0/supported-os.md. We have not had a good process for defining that (not specific to Android).

When I say "what do we need to do", I mean both broadly and mechanically (ex: update these version strings in this file).

[jpobst]

The real q is what is it that we need to do to feel comfortable adding a new version to our support docs?

This aspect of Android OS support is probably determined more by the dotnet/runtime team. They ensure that .NET/Mono runs on each version of Android.

cc: @steveisok

[richlander]

I was wondering that going into this.

@steveisok -- Can you ensure that our new OS onboarding doc sufficiently describes how we validate a new Android version (same for iOS)? Doc: https://github.com/dotnet/runtime/blob/main/docs/project/os-onboarding.md

[steveisok]

The real q is what is it that we need to do to feel comfortable adding a new version to our support docs?

This aspect of Android OS support is probably determined more by the dotnet/runtime team. They ensure that .NET/Mono runs on each version of Android.

Operationally, I think it's pretty straightforward. We make sure the latest SDK is installed on the android docker container that we test on and make sure the emulator we launch is set up to use it. If the tests pass, then runtime is good to go. I would argue it is also important to run tests against dotnet/android since they repackage the runtime and do some creative things.

[steveisok]

/cc @vitek-karas

[steveisok]

@steveisok -- Can you ensure that our new OS onboarding doc sufficiently describes how we validate a new Android version (same for iOS)? Doc: https://github.com/dotnet/runtime/blob/main/docs/project/os-onboarding.md

I think it covers the gist. Should we point out the support matrix differences with our mobile platforms?

https://dotnet.microsoft.com/en-us/platform/support/policy/maui

[richlander]

The support model differences are primarily relevant for the branches we need to touch, right? That raises another question. When MAUI goes out of support for .NET 8, do we remove the Android and iOS test/build legs?

With Android 16 coming out, will you update runtime:main to Android 16?

[steveisok]

The support model differences are primarily relevant for the branches we need to touch, right? That raises another question. When MAUI goes out of support for .NET 8, do we remove the Android and iOS test/build legs?

We haven't done a good job of it in the past, but we should.

With Android 16 coming out, will you update runtime:main to Android 16?

Yes, either @vitek-karas's team or my team will handle it.

[richlander]

Please add any missing context (including updating support docs) to the onboarding doc. I happily accept PRs!

If a new OS is reasonably stable, we can move to it ahead of its GA, in main, per #111768 (comment).