372
edits
Changes
Semantic Versioning/1.17 (view source)
Revision as of 05:51, 6 December 2021
, 05:51, 6 December 2021Copy Semantic Versioning to MC1.17 archive
[https://semver.org/ Semantic Versioning] is a versioning system where three variable are used to represent the version, in the format of <code>MAJOR.MINOR.PATCH</code>. 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.
{{Tip|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 <code>0</code>. For instance, if <code>MINOR</code> would increment, <code>PATCH</code> would become <code>0</code>. If <code>MAJORMOD</code> would increment, all other variables would become <code>0</code>.
== Hybrid Versioning ==
A good hybrid of Semantic Versioning for Minecraft mods is the format: <code>MCVERSION-MAJORMOD.MAJORAPI.MINOR.PATCH</code>.
{|
! Variable !! Description
! When to Change
|-
| <code>MCVERSION</code> || The Minecraft version being targeted.
| The target Minecraft version is updated.
|-
| <code>MAJORMOD</code> || The major version of the mod.
| Exising mod objects - such as items, blocks, tile entities - are removed or fundamental mechanics are modified.
|-
| <code>MAJORAPI</code> || 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.
|-
| <code>MINOR</code> || The minor version of the mod.
| Mod objects or non-fundamental mechanics are added, or elements of the API are deprecated (but not removed).
|-
| <code>PATCH</code> || 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 <code>-betaX</code>, where <code>X</code> 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 <code>MINOR</code> variable) and others updated before applying this classifier.
{{Tip/Important|This guide does not use the <code>-preX</code> classifier for pre-releases, because the library used to compare versions does not accept it as an alias for <code>-betaX</code>.}}
=== 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 <code>-rcX</code> classifier, where <code>X</code> 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 <code>MINOR</code> 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 <code>-final</code> classifer. This denotes that the mod will no longer be supported for the denoted <code>MCVERSION</code> 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 <code>MAJORMOD</code> and <code>MAJORAPI</code> should be kept at <code>0</code>. Only <code>MINOR.PATCH</code> 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 <code>MAJORMOD</code> version, reset the others to <code>0</code>, and follow your versioning strictly.
{{Tip|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 <code>0</code>. For instance, if <code>MINOR</code> would increment, <code>PATCH</code> would become <code>0</code>. If <code>MAJORMOD</code> would increment, all other variables would become <code>0</code>.
== Hybrid Versioning ==
A good hybrid of Semantic Versioning for Minecraft mods is the format: <code>MCVERSION-MAJORMOD.MAJORAPI.MINOR.PATCH</code>.
{|
! Variable !! Description
! When to Change
|-
| <code>MCVERSION</code> || The Minecraft version being targeted.
| The target Minecraft version is updated.
|-
| <code>MAJORMOD</code> || The major version of the mod.
| Exising mod objects - such as items, blocks, tile entities - are removed or fundamental mechanics are modified.
|-
| <code>MAJORAPI</code> || 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.
|-
| <code>MINOR</code> || The minor version of the mod.
| Mod objects or non-fundamental mechanics are added, or elements of the API are deprecated (but not removed).
|-
| <code>PATCH</code> || 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 <code>-betaX</code>, where <code>X</code> 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 <code>MINOR</code> variable) and others updated before applying this classifier.
{{Tip/Important|This guide does not use the <code>-preX</code> classifier for pre-releases, because the library used to compare versions does not accept it as an alias for <code>-betaX</code>.}}
=== 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 <code>-rcX</code> classifier, where <code>X</code> 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 <code>MINOR</code> 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 <code>-final</code> classifer. This denotes that the mod will no longer be supported for the denoted <code>MCVERSION</code> 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 <code>MAJORMOD</code> and <code>MAJORAPI</code> should be kept at <code>0</code>. Only <code>MINOR.PATCH</code> 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 <code>MAJORMOD</code> version, reset the others to <code>0</code>, and follow your versioning strictly.