Rules for API level/version

[fatcerberus]

I figured I should lay out the ground rules for the new Android-like API level system.

API version is always integral ("2.0") and represents a baseline standard. Within a version functionality can only be added or deprecated, never removed or changed in an incompatible way. Games written against a specific API version will remain functional on any future engine declaring that version.

API level represents the level of feature support. Games written against a specific API level should work with any higher level as well. When the standard is expanded without breaking compatibility, this gets bumped. I would recommended we try to do this in waves, with incremental enhancements being introduced first as extensions (exposed through engine.extensions) to avoid too much proliferation of API levels.

We should strive to avoid bumping the API version at all costs. This should only be done when the API gets too clogged with legacy baggage and is desperately in need of overhaul (like the Sphere 1.x API is now).

[fatcerberus]

I'm also thinking the API level a game is written against should be encoded in the manifest, so that the engine can check whether it's compatible on startup. Same for (required) extensions.

I do have a system like this already in minisphere but it's just kind of a curiosity for now because we haven't actually codified anything yet.

[joskuijpers]

I think putting in the manifest the supported API versions is fine.
I do think that level 22 should support games built on level 21. Even if it is marked deprecated stuff. Then you could check against minimum versions.

Keep the api level a whole number if you want to go the Android way, otherwise use SemVer.

Yeah SphereDev is down :(

[fatcerberus]

Right, any given API level is meant to be compatible with any lower level. If compatibility is ever broken, the API version must be bumped, i.e. 2.0 -> 3.0. That's a "last resort" for when the API is so full of deprecated stuff that it needs to be cleaned up.