Issue description
It's well known by now that the API versioning introduced last year (as documented in #179) is not very good at properly describing the server API.
Background
expand
Back at MCPE 1.0, API-breaking backwards-incompatible changes were made (due to the chunk handling rewrite). This necessitated a major version bump as described under the original SemVer API versioning.
To recap, semver is composed of x.y.z, or major.minor.patch:
- Major: Breaking changes that are not backwards compatible. ANY breaking change (regardless of how big or small it is) requires a major API bump.
- Minor: New feature additions or other alterations which are backwards-compatible, but dependents using these additions cannot function on earlier versions.
- Patch: Bug fixes which are not BC-breaking which should be a no-brainer to upgrade to.
As of December 2016 we had come to the conclusion that there was a significant amount of work to be done on PocketMine-MP which would require freedom to make backwards-incompatible changes whenever necessary. This was a problem because it would require a major API version bump every time any backwards-incompatible change was made at all, which would probably put us on something like API version 700.0.0 by now. This is obviously not acceptable.
This led to the introduction of the ALPHA and other suffix schemes, where any ALPHA may have breaking changes in between versions. This was an attempt to remove the need for major API bumps for the frequent breaking changes, while providing plugin developers with something to work against for a specific version.
Problem
expand
This has self-evidently not worked as intended, and in hindsight the ALPHA API versioning is highly flawed. As stated by @SOF3 , the current system is no different from SemVer except for the fact the effective major version is constantly being bumped, and nothing else.
The ALPHA system also does a poor job of describing addition of features and bugfixes. Any and all changes are aggregated into the next ALPHA release, resulting in large mixed changelogs. When users upgrade to a new ALPHA version, they have no idea if everything or nothing will break, which effectively renders the 3.point API version useless.
As it stands with the current definition of an "ALPHA" we are likely to never make it out of "ALPHA" since breaking changes are frequently made to Minecraft PE, which then frequently result in breaking API changes necessary to the core code. A perpetual state of ALPHA becomes meaningless when everyone is using it in production and it's likely to never end. This situation is obviously unacceptable.
Proposal
After several months of discussions, I have come up with a proposal for a new, more sane way of versioning the API. This breaks away from SemVer, since SemVer is impractical to apply to MCPE-related things (as earlier discussed), and also because PocketMine-MP is not very modular (SemVer doesn't apply very well to projects with very large exposed API).
The proposed new versioning scheme consists of a 3-point x.y.z system which is more rational to the user.
- Major: This is bumped when big things change the entire API in a backwards-incompatible way, which will affect anything and everything. ALPHA7 is a good example of when this version might be bumped (the entire API was broken). This is locked to a single number (e.g. 4.0.0 is not compatible with 3.0.0)
- Minor: This is changed when there are isolated backward-incompatible changes in one area of the API that might affect some plugins. This is also locked to a single number, so other numbers are not compatible (e.g 3.1.0 is not compatible with 3.2.0)
- Patch: This is changed when features and bugfixes are added in a backwards-compatible fashion. This is not locked to a single number, but the plugin number must be <= the server number (e.g. plugin 3.2.0 is compatible with server 3.2.1, but not vice-versa).
Comments and suggestions
Are welcomed, please comment on the issue.
Category: API Category: Core Resolution: Completed