Semantic Versioning 2.0.0 Documentation

Semantic Versioning (SemVer) is a versioning scheme designed to address challenges in software management, particularly with regard to handling dependencies. The version number follows the format MAJOR.MINOR.PATCH, with specific guidelines for incrementing each component:

• MAJOR: Incompatible API changes.
• MINOR: Backward-compatible functionality additions.
• PATCH: Backward-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to this format.

Introduction

In the world of software development, the issue of “dependency hell” often arises as systems expand and dependencies increase. SemVer proposes a solution through a set of rules for version assignment and incrementation, based on established practices in both closed and open-source software.

Public API Declaration

Software utilizing SemVer must declare a public API, either within the code or through comprehensive documentation. The public API serves as the foundation for version incrementation.

Version Format

The version format X.Y.Z (Major.Minor.Patch) is employed, where X, Y, and Z are non-negative integers. Leading zeroes are not allowed. This format conveys different types of changes:

• PATCH: Backward-compatible bug fixes.
• MINOR: Backward-compatible functionality additions.
• MAJOR: Incompatible API changes.

Semantic Versioning Specification (SemVer)

Key guidelines for SemVer include:

1. No Modification of Released Versions: Once a versioned package is released, its contents must not be modified. Any changes must be released as a new version.
   Example:

1.2.3 # Released version
1.2.4 # New version with bug fix

2. Major Version Zero (0.y.z): Represents the initial development stage, where anything may change at any time. The public API is not considered stable.
Example:

0.1.0 # Initial development version

3. Version 1.0.0: Defines the stable public API. Subsequent version increments depend on changes to this API.
Example:

1.0.0 # Stable version with a defined public API

4. Incrementing Patch, Minor, and Major Versions: Guidelines for incrementing version numbers based on the nature of changes introduced.
Example:

1.2.3 # Patch version increment for bug fix
1.3.0 # Minor version increment for backward-compatible functionality
2.0.0 # Major version increment for incompatible API changes

5. Pre-release Versions: Denoted by appending identifiers after the patch version, indicating instability and potential incompatibility.
Example:

1.0.0-alpha # Pre-release version indicating instability
1.0.0-beta.1 # Another pre-release version with specific identifier

6. Build Metadata: Appended with a plus sign, it includes identifiers but does not affect version precedence.
Example:

1.0.0+001 # Version with build metadata

7. Precedence Calculation: How versions are compared, with a hierarchy based on Major, Minor, Patch, and pre-release identifiers.
Example:

1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 # Major, Minor, Patch comparison
1.0.0-alpha < 1.0.0 # Pre-release version has lower precedence
1.0.0-alpha.1 < 1.0.0-alpha.beta # Precedence in pre-release versions

These guidelines ensure that version numbers convey meaningful information about code changes and compatibility, facilitating effective software management.