Semantic Versioning (SemVer) Cheat Sheet

Semantic Versioning (SemVer) is a versioning scheme that provides a standard way of describing the version of software libraries or applications. Here’s a cheat sheet for Semantic Versioning:

Version Format

A version number is represented as MAJOR.MINOR.PATCH.

Incrementing Versions

  • MAJOR Version:
    • Increment when incompatible API changes are introduced.
  • MINOR Version:
    • Increment when new features are added in a backward-compatible manner.
  • PATCH Version:
    • Increment for backward-compatible bug fixes.

Pre-release Versions

Pre-release versions can be denoted with a hyphen and a series of dot-separated identifiers immediately following the PATCH version.

  • Example: 1.0.0-alpha, 1.0.0-beta.2

Build Metadata

  • Build metadata can be denoted with a plus sign and a series of dot-separated identifiers immediately following the PATCH or pre-release version.
    • Example: 1.0.0+20130313144700

Version Range

  • Specify a Range in Package.json:
    • ^1.0.4 means any version that is compatible with 1.0.4 and does not include breaking changes.
  • Specify an Exact Version:
    • 1.0.4 means only version 1.0.4.

Versioning Practices

  • Initial Release:
    • Start with version 1.0.0.
  • Backward-Compatible Bug Fixes:
    • Increment the PATCH version.
  • New Features in a Backward-Compatible Manner:
    • Increment the MINOR version.
  • Incompatible API Changes:
    • Increment the MAJOR version.

Best Practices

  • Follow Semantic Versioning:
    • Adhere to the rules of Semantic Versioning for consistent versioning across projects.
  • Communicate Changes:
    • Use clear release notes to communicate changes between versions.
  • Use Tools:
    • Utilize tools and scripts that support SemVer.

Examples

  • Valid Version Examples:
    • 1.0.0, 2.3.1, 1.0.0-alpha.1, 1.2.3+build.456
  • Invalid Version Examples:
    • 1, 1.0, 1.02, 1.0-beta

Remember that Semantic Versioning is a convention, not a requirement. However, following SemVer best practices helps maintain a consistent and predictable versioning scheme for software projects. Refer to the official Semantic Versioning Specification for detailed guidelines.