Semantic Versioning Explained

Communicate the impact of every change through version numbers — enabling safe dependency updates and clear expectations for consumers.

Semantic Versioning

Semantic versioning (SemVer) is a versioning scheme using a three-part format — MAJOR.MINOR.PATCH — that communicates the nature and impact of changes through version number increments.

Explanation

SemVer uses three numbers: MAJOR (incremented for breaking changes), MINOR (incremented for new backward-compatible features), and PATCH (incremented for backward-compatible bug fixes). This gives users immediate understanding of change impact: upgrading from 2.3.1 to 2.4.0 is safe (new features, no breaks), while upgrading from 2.x to 3.0.0 may require code changes. Pre-release versions use suffixes (1.0.0-alpha.1). SemVer is the standard for npm, PyPI, and most package registries, enabling dependency managers to automatically install compatible updates.

Bookuvai Implementation

Bookuvai follows SemVer for all packages and APIs. CI/CD automatically validates version bumps based on change type. We use tools like conventional commits and semantic-release to automate version determination from commit messages.

Key Facts

  • MAJOR.MINOR.PATCH format communicates change impact
  • MAJOR: breaking changes, MINOR: new features, PATCH: bug fixes
  • Standard for npm, PyPI, and most package registries
  • Enables automatic safe dependency updates
  • Pre-release suffixes (-alpha, -beta, -rc) for unreleased versions

Related Terms

Frequently Asked Questions

What counts as a breaking change?
Any change that requires consumers to modify their code: removing or renaming APIs, changing return types, altering default behavior, removing configuration options, or requiring new minimum versions of dependencies.
What is semantic-release?
Semantic-release automates version determination from commit messages. Commits following conventional commit format (feat:, fix:, BREAKING CHANGE:) automatically trigger the correct version bump, changelog generation, and package publishing.
Should I use SemVer before version 1.0.0?
Pre-1.0 versions signal instability — any change can be breaking. Use 0.x.y during initial development. Once the API is stable and used in production, release 1.0.0 to signal that SemVer guarantees now apply.