How will the "minor API level" be exposed in the NDK?

[mhsmith]

Hi, I'm the maintainer of Android support for the Python programming language, which was added in Python 3.13.

I've just seen this post, which announces that there will now be two Android SDK releases each year:

The minor release in Q4 will include new APIs, but, like the incremental quarterly releases we have today, will have no planned behavior changes, minimizing the need for compatibility testing. To differentiate major releases (which may contain planned behavior changes) from minor releases, minor releases will not increment the API level. Instead, they'll increment a new minor API level value, which will be accessed through a constant that captures both major and minor API levels. A new manifest attribute will allow you to specify a minor API level as the minimum required SDK release for your app.

In Python we're already using the API level in our packaging metadata to indicate the required Android version. So I have a couple of questions about how this change will affect the NDK:

• Will minor releases also include new native APIs?
• If so, how will this be managed, given that the __ANDROID_API__ macro only has space for a single integer?

I understand you must have discussed this internally, but I don't really see why the concept of a "minor API level" is necessary at all. The Android versioning system is complicated enough already, what with version numbers and API levels and alphabetic code names, which I have to look up in a table all the time. That's why I chose to make Python use the API level, because it's a simple integer which can be compared numerically. It would be unfortunate to lose that simplicity.

If there will be a new "constant that captures both major and minor API levels" – presumably something like (major * 100) + minor – then why not just make that the API level? You could even base it on the user-visible Android version number, so that the next API level for Android 16 would be 1600, and there would be one less thing that everyone needs to remember.

[DanAlbert]

I'll do my best to answer, but I'm also mostly on the receiving end of this rather than the decision making end. I'll pass this on to the right folks though :)

Will minor releases also include new native APIs?

It's permitted, though native APIs are added much less often than SDK APIs so the move to quarterly increases the likelihood that a given release might have no new NDK APIs. The truth is we don't really know how this will play out yet. I expect from an NDK perspective a minor release is going to look a lot like a lightweight major release does today, but we won't really know for sure until it starts happening.

If so, how will this be managed, given that the ANDROID_API macro only has space for a single integer?

I believe the plan is to add a second macro to capture the minor version. I know a combined int has been suggested but I'm not sure if that's part of the plan or not.

The Android versioning system is complicated enough already, what with version numbers and API levels and alphabetic code names... That's why I chose to make Python use the API level, because it's a simple integer which can be compared numerically. It would be unfortunate to lose that simplicity.

I'm right there with you. As you discovered, the only one of those that really matters is the API level.

Honestly, you can probably stick with what you have until you've got a reason to change. Unless you're going to start adding packages for the NDK APIs themselves, I expect it'll be very rare that any Python package maintainer to be aware of the minor SDK version. Annual API upgrades should be plenty for staying on top of any new libc APIs you need, and the rest probably don't show up in Python code anyway. For app developers, adding that additional data to places like platform is probably helpful even if wheels don't acknowledge the minor API levels (though if I were you I'd wait until the SDK/NDK flavors of this ship and stick and then just copy us).

Realistically most app developers don't jump on new APIs right away anyway, because the cost to develop the new features isn't worth it until they can be used on a wide array of devices¹. As you say in the PEP, that can take years. By the time the new APIs are broadly available, targeting the first major version that included them rather than the minor version that introduced them probably doesn't actually exclude many users? I could be totally wrong on that. It's one of those things we won't know until it happens. If it turns out I'm wrong and you do need that information in wheels, you can always extend it once it becomes clear that it's needed rather than doing all the work now to find out it's unnecessary.

Hi, I'm the maintainer of Android support for the Python programming language, which was added in Python 3.13.

Thank you, btw. We didn't know that was going on until we saw it in the release notes and were pleasantly surprised to find that it looked to be exactly what we'd have suggested. If you ever run into questions, you know where to find us :)

Footnotes

1. There are exceptions to this rule for certain types of APIs: anywhere the API can be used at massive scale such as in a major game engine is much more likely to pick things up quickly. That's maybe something that pygame would be interested in. ↩

[mhsmith]

Thanks very much, that all makes sense.