Skip to content

Instantly share code, notes, and snippets.

@zekroTJA

zekroTJA/mc-modpack-semver.md

Last active February 11, 2024 15:53
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save zekroTJA/8ae61a4e2a055a4fbd4552e306cb3ad7 to your computer and use it in GitHub Desktop.
Save zekroTJA/8ae61a4e2a055a4fbd4552e306cb3ad7 to your computer and use it in GitHub Desktop.
Download ZIP
Semantic Versioning of Minecraft Modpacks
Raw
mc-modpack-semver.md

Semantic Versioning of Minecraft Modpacks

v.1.0.0-rc.2
2020-07-09

Summary

The version number goes after follwoing format.

Simple:    MAJOR.MINOR.PATCH
Extended:  MAJOR.MINOR.PATCH-PRERELEASE_EXTENSION.SUBVERSION

Given the format above, increment the:

  1. MAJOR version when changes are applied which are incompatible with existing game maps.
  2. MINOR version when changes are applied which are incompatible with the previous server version.
  3. PATCH version when changes are applied which are compatible with the previous server version and game map.

Introduction

This document is strongly inspired by the original Semantic Version documentation which is widely used and accepted in software development. The goal of this specification is to simplify the handling of Minecraft modpack servers and game maps on updating a modpack.

This proposal is designed to help bypassing problems like decide when to update the server with a new modpack version or even when it is necessary to update or re-create the game map with a major modpack update.

If you want to read more about the details behind Semantic Versioning in software engineering, read the original SemVer specification at https://semver.org.

Semantic Version Specification - Minecraft Modpack Derivation

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

  1. A normal version number MUST take the form of X.Y.Z where X, Y and Z represent non-negative integers and MUST NOT contain leading zeroes. X defines the MAJOR version, Y defines the MINOR version and Z defines the PATCH version. Each of these elements MUST increase numerically. An increase MUST be an addition of one (1) to the current verion number.

  2. Once a versioned release has been published, the contents of that version package MUST NOT be modified after. Any modifications MUST result in a new package with a new version number.

  3. MAJOR version zero (0.Y.Z) defines an initial development state which SHOULD NOT be considered stable.

  4. PATCH version Z MUST be incremented if only backwards compatible changes are introduced which are compatible to the previous server release and to game maps created with the previous client version.

  5. MINOR version Y MUST be incremented if changes are introduced which are not compatible with the previous version of the server release but are compatible with game maps created in the previous client version. An increment of the MINOR version MUST set the PATCH version to zero (0).

  6. MAJOR version X MUST be incremented when changes are introduced which are not compatible with the previous version of the server and which are not compatible to a game map which was created with a previous client version. PATCH version Z and MINOR version Y MUST be reset to zero (0) after MAJRO version increase.

  7. A pre-release version MAY be denoted by appending a hyphen and a series of dot-seperated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.
    Examples: 1.1.0-alpha, 1.1.0-beta, 1.1.0-beta.1, 1.1.0-rc.1.2, 1.1.0-1.3.6.

  8. Build metadata or additional version information MAY be denoted by appending a plus sign (+) and the specific string as identifier immediately following the patch or pre-release version. This identifier MUST comprise only ASCII alphanumerics and hyphens. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.
    Examples: 1.1.0+6213, 1.1.0-rc.1+sha613fd3e, 1.1.0-beta+3fe28e17.

  9. Precedence MUST be calculated by seperating the versions into MAJOR, MINOR, PATCH and pre-release identifiers in that specific order. Build metadata SHALL NOT figure into precedence. Precedence is determined by the first difference when comparing each of these identifiers from the left to right. These identifiers are always compared numerically.
    Example: 1.1.0 < 1.2.0 < 1.2.1 < 2.0.0.
    When MAJOR, MINOR and PATCH are equal, a pre-release version has lower precedence than a normal version.
    Example: 1.0.0-beta < 1.0.0.
    Precedence for two pre-release version with the same MAJOR, MINOR and PATCH version MUST be determined by comparing each dot-seperated identifier from left to right until a difference is found as following:

    1. Identifiers consisting of ony digits are compared numerically.
    2. Identifiers with letters or hyphens are compared lexically in ASCII sort order.
    3. Numeric identifiers always have lower precedence than non.numeric identifiers.
    4. A large set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.

    Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Additional Notice

You may also give different PATCH and pre-release versions for your server and client instances, if prefered.

Example:

Client Server Compatibility
1.1.0 1.1.0 1.1
1.1.1
1.1.2
1.2.0-rc.1 1.2.0-rc.1 1.2.0-rc
1.2.0 1.2.0 1.2.
1.2.1
1.2.1

About

This document is strongly inspired and influenced by the Semantic Version Specification 2.0.0.

The Semantic Versioning specification was originally authored by Tom Preston-Werner, inventor of Gravatar and cofounder of GitHub.

THis document is licenced under the Creative Commons - CC BY 3.0 licence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment