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.

The information presented here is purely informative. You are free to use any versioning system you wish.

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

This guide does not use the -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.