Semantic Versioning/1.17
Semantic Versioning is a versioning system where three variable are used to represent the version, in the format of MAJOR.MINOR.PATCH. However, in the case of modding, it may be beneficial to add additional variable such as the Minecraft version, to allow distinction between mods that work for which Minecraft versions.
When incrementing any variable, all lesser variables should reset to 0. For instance, if MINOR would increment, PATCH would become 0. If MAJORMOD would increment, all other variables would become 0.
Hybrid Versioning
A good hybrid of Semantic Versioning for Minecraft mods is the format: MCVERSION-MAJORMOD.MAJORAPI.MINOR.PATCH.
| Variable | Description | When to Change |
|---|---|---|
MCVERSION |
The Minecraft version being targeted. | The target Minecraft version is updated. |
MAJORMOD |
The major version of the mod. | Exising mod objects - such as items, blocks, tile entities - are removed or fundamental mechanics are modified. |
MAJORAPI |
The major version of the mod's API. | Any part of the mod's public-facing API is changed, such as reordered enums, method signature changes, or removal of public methods. |
MINOR |
The minor version of the mod. | Mod objects or non-fundamental mechanics are added, or elements of the API are deprecated (but not removed). |
PATCH |
The patch version of the mod release. | Bugs are fixed or the changes are unnoticable. |
Classifiers
A classifer can be appended to the build version to denote it is a special build of some note. These classifiers are appended after the version variables are incremented and reset.
Pre-releases
It is also possible to pre-release work-in-progress features, which means new features are released that are not quite done yet. These can be seen as a sort of "beta". These versions should be appended with -betaX, where X is the number of the pre-release. Already released versions before the initial release can not go into pre-release; a variable must be incremented (e.g. the MINOR variable) and others updated before applying this classifier.
Important
-preX classifier for pre-releases, because the library used to compare versions does not accept it as an alias for -betaX.Release Candidates
If you are confident enough that a build is ready to be a release but a bit more testing is required, you may make it a release candidate. These release candidates may receive the -rcX classifier, where X is the number of the release candidate, incremented for every new release candidate build. Already released versions before the initial release can not go into pre-release; a variable must be incremented (e.g. the MINOR variable) and others updated before applying this classifier.
The final released build will have the same version as the release candidate with the classifier omitted, and will usually be exactly the same or have a few unnoticable bugfixes included.
Final Release
When dropping support for a Minecraft version, the final build for that Minecraft version may receive the -final classifer. This denotes that the mod will no longer be supported for the denoted MCVERSION and players should upgrade their Minecraft version to continue receiving updates and fixes.
During Development
If you are in the initial development stage of your mod (before any official releases), the MAJORMOD and MAJORAPI should be kept at 0. Only MINOR.PATCH should be updated every time you build your mod. During this development stage, you are free to change or restructure your mod's API, objects, and mechanics as you wish without updating the major version variables. Once you build an official public release, you should increment the MAJORMOD version, reset the others to 0, and follow your versioning strictly.