Version the public API

[Ruin0x11]

trafficstars

Related Issues

Description

The API needs to be versioned if it's to be used publicly.

I'm thinking there should be a monotonically incrementing number, accessable through Env.api_version(), so it's easily compared against a target version with comparison operators. Every time a file under api/ is changed in an incompatible manner, the number should be incremented. "Incompatible" could be ambiguous so we could just use the heuristic of changing any file under api/, but this could be confusing for things like bug fixes or optimizations that don't affect existing code. Of course, it's possible to get it wrong also and accidentally affect behavior that shouldn't have been changed, so it might be a good idea to just increment it always.

Also there needs to be extremely clear documentation over each change. Pull requests that modify api/ should not be accepted without recording the changes made in a machine-readable format. This is to enable searching for changes between versions more easily.

An an example of this use case, it's difficult to search through Minecraft's documentation over changed API methods/classes in the MCP project, because some of it is recorded in Markdown instead of a machine-readable format with a standardised schema. Since it also uses an IRC bot instead of a website to search for things you have to sign up for and use IRC to access the data, increasing friction.

Ideally, the way this system is designed should make it possible to create a website which provides:

• A list of changes per API version. They should be typed per the change (added/removed method argument, added/removed function, etc.) and machine readable as well as formattable.
• A way to search for an identifier across all API versions and find where it was added/removed/changed.
• A way to search for a specific API version to know what was changed. This will be really useful when you start seeing code like if Env.api_version() < 26 then ... end and want to know what was added/removed in that version.

I'm not sure of the extent that semver should be used for the base distribution, since pull requests can implement a single API method without necessitating a whole version bump. Supporting both an integer version number and semver means having two sources of truth, though. Maybe major releases could be defined as constant integers per the API version they represent. Semver also has its own issues if you make behavioral changes based on the kind of version incremented, because different people can have different ideas of what constitutes "major" or "minor", and it can easily be misused otherwise.

Once this system is in place we can't go back, so it should be carefully thought over.

[Ruin0x11]

Note to self: Explicit Versioning is designed to signal compatible and incompatible changes, unlike Semver. Not sure if the multiple digits is still worth using, but the signaling is important. It means we can forbid version specifiers like 1.* and allow 1.0.* at maximum, because incrementing the larger digits has meaning.