Consolidate mappings for all known Android versions, code names, and API levels

[pjcollins]

Xamarin.Android is currently responsible for generating and installing AndroidApiInfo.xml files alongside Mono.Android.dll to help provide a full mapping of Android version information. For reference, these files look like this:

<AndroidApiInfo>
  <Id>30</Id>
  <Level>30</Level>
  <Name>R</Name>
  <Version>v11.0</Version>
  <Stable>True</Stable>
</AndroidApiInfo>

While these files are great at providing context around the Android versions that a current installation of Xamarin.Android supports, they do not provide a full story with respect to all known Android versions. As a fall back, we have this hardcoded mapping:

xamarin-android-tools/src/Xamarin.Android.Tools.AndroidSdk/AndroidVersions.cs

Line 142 in f2af06f

public static readonly AndroidVersion [] KnownVersions = new [] {

However we often forget to update this list, and it is duplicated in:
https://github.com/xamarin/xamarin-android/blob/f361d997807504a69c29163811f362da701410b6/build-tools/xaprepare/xaprepare/ConfigAndData/BuildAndroidPlatforms.cs#L11

I can see a couple of options to improve this:

1. Remove the duplication from xamarin-android, and have the xamarin-android build use Xamarin.Android.Tools.AndroidVersions.KnownVersions.
2. Remove the duplication from xamarin-android-tools, and have the XA build generate and install a KnownAndroidApiInfo.xml file which contains a full set of known version information.

[jonpryor]

The reason it's in xamarin-android-tools is because androidtools also needs the data, plus various other dependencies. We thus want xamarin-android to be the "source of truth", but don't want it to provide the API for the source of truth. (Which is kinda how it works now: xamarin-android creates the AndroidApiInfo.xml files, while xamarin-android-tools reads those files to implement AndroidVersions.)

But wait, it gets different/worse! Part of the intent behind the use of AndroidApiInfo.xml files was so that the IDE could be "dynamic", and automagically "pick up" new API levels without requiring code changes.

As originally conceived, there would be one AndroidApiInfo.xml file per $(TargetFrameworkVersion) value.

The problem is that in our forthcoming .NET 6+ world order, there is only "one" $(TargetFrameworkVersion) value, not 13+.

We thus need a "re-conception" of how this should work, ideally in a manner which preserves the current system's "dynamism" (which we're gonna need in ~4-6 months once API-32 previews are available…). A KnownAndroidApiInfo.xml file would be such an idea, but we also need to figure out how to find it in a manner which works everywhere it's needed.

[pjcollins]

The changes to only ship one (or one stable, one preview) AndroidApiInfo.xml file in .NET 6 definitely highlight part of the problem. However, we also need a solution for maintaining a mapping of Android version info for all known versions, not just the installed ones moving forward.

I think it would be preferable not to continue to have to update both of these files whenever a new version comes along?

xamarin-android-tools/src/Xamarin.Android.Tools.AndroidSdk/AndroidVersions.cs

Line 142 in f2af06f

public static readonly AndroidVersion [] KnownVersions = new [] {

and
https://github.com/xamarin/xamarin-android/blob/f361d997807504a69c29163811f362da701410b6/build-tools/xaprepare/xaprepare/ConfigAndData/BuildAndroidPlatforms.cs#L11

[jonpryor]

@pjcollins wrote:

I think it would be preferable not to continue to have to update both of these files…

Is it preferable?

Paraphrasing, I believe your argument is that it is "bad" to have two different "sources of truth":

1. The set of AndroidApiInfo.xml files (and/or a future hypothetical KnownAndroidApiInfo.xml file), and
2. The AndroidVersions.KnownVersions array.

I disagree that this is "bad". "Not ideal", perhaps, but explicitly not "bad". The scenario is one of "what needs to be done for the IDE to know about a new version?" Prior to aad97f1, the effective answer was "update xamarin/androidtools and then bump 'everything' which depends on that data." It made for a miserable experience.

Now we're "file based"; updating the IDE "simply" requires ensuring that the appropriate AndroidApiInfo.xml file exists. No submodule bumps required!

So now we have a concern of historical data. However, current data is "historical" data. To my mind, it has the same concerns.

Thus, I think "duplication" is preferable to the previous machinations. It's useful for AndroidVersions to be able to read files-on-disk to determine the "current" state of the world, and "merge" that with a "historical" view. (And if the files-on-disk contains the entire history? So much the better!)

Which is the problem with AndroidVersions.KnownVersions: it can't be overridden, it can't participate in file overrides, and it never should have been made public in 10c3d50; see also #61.

Thus, the question: do we actually want "consolidation"? I'm not currently convinced that we do. What we want, and kinda have, is an API which merges information from multiple sources. The AndroidVersions API should be the "source of truth", mediating between multiple sources of data.

If we need "historical data", then we need to determine what we need regarding historical data, which is not AndroidVersions.KnownVersions.

Do we need access to "CodeName"?

partial class AndroidVersions {
    public string? GetCodeNameFromId (string id);
}

[pjcollins]

The duplication that I think is "bad" and would like to try to avoid is the duplication between what's in the xaprepare tool and what's in this repo (AndroidVersions.KnownVersions). Maybe the simplest answer to avoid maintaining two hardcoded lists would be to figure out a way to have the Xamarin Android build use AndroidVersions.KnownVersions instead of Xamarin.Android.Prepare.BuildAndroidPlatforms.AllPlatforms? Right now we are in a place where Xamarin.Android.Prepare.BuildAndroidPlatforms.AllPlatforms knows about more Android Versions than AndroidVersions.KnownVersions, and I think it would be better if we didn't have to remember to update both of these lists every time a new version comes around.

Second to that is the historical data question, and what information callers need access to. I think we need to be able to reason about Android Version information for the versions that XA does not ship, and for all of those versions we need to be able to compare / convert between all of the version "representations" (e.g API Level <-> OS Version <-> Code Name).

[jonpryor]

What is the harm in the duplication? The benefit is that when we need to add support for API-T next spring, we won't need a xamarin-android-tools bump in xamarin-android in order to provision the API-T files. (Not needing a submodule bump for PR builds of preview features is a benefit!)

Quasi-related, I'm not sure why xaprepare needs all those versions anyway. Why does it need anything prior to API-19, anything lacking a framework: parameter?

We should expect there to be occasional differences between the table in xamarin-android and AndroidVersions.KnownVersions. Removing this "duplication" will only serve to make supporting future preview releases harder.

[pjcollins]

The harm I see is that historically we forget to update AndroidVersions.KnownVersions, multiple sources of the same information inevitably leads to missing updates in one place or another. Perhaps I could just add comment in the XA side to come update this repo when that one is being updated.

[pjcollins]

I opened xamarin/xamarin-android#6419 and #141 for now. I think we can keep this open to try to track effort to make KnownVersions private again.

[jonpryor]

Might also be handy if the consolidated version info also could contain the highest supported NDK version.