Semantic versioning

Semantic versioning, often shortened to SemVer, is a version numbering convention for software: MAJOR.MINOR.PATCH (for example 2.4.1), where each part signals a specific kind of change.

What is semantic versioning?

A developer or a package manager can tell, just by reading a version string, whether upgrading a dependency is safe or likely to break something. SemVer was formalized by Tom Preston-Werner and is now the de facto standard across npm, Composer, Cargo and most modern package ecosystems.

How version numbers work

Given a version MAJOR.MINOR.PATCH:

• MAJOR increments on incompatible, breaking API changes (1.9.0 to 2.0.0).
• MINOR increments when functionality is added in a backward-compatible way (2.0.0 to 2.1.0).
• PATCH increments for backward-compatible bug fixes (2.1.0 to 2.1.1).

A dependency declared as ^2.1.0 in a package.json tells a package manager it can safely install any 2.x.x release, but never 3.0.0, since that would signal a breaking change.

Pre-release and build metadata

SemVer also defines optional suffixes for versions that are not yet stable:

• 1.0.0-alpha, 1.0.0-beta.2, 1.0.0-rc.1: pre-release identifiers, sorted before the final release.
• 1.0.0+20260923: build metadata, ignored when comparing precedence between versions.

Semantic versioning vs. calendar versioning

Best practices and common pitfalls

Bump the MAJOR version for every breaking change, even a small one, since consumers rely on that signal to decide whether to upgrade automatically. A frequent mistake is shipping a breaking change as a MINOR or PATCH release, which silently breaks downstream projects that trusted the version range. Use pre-release tags such as -beta or -rc to let early adopters test changes before a stable release, and document breaking changes in a changelog alongside each MAJOR bump.

Compatibility impact

Semantic versioning directly affects how safely a project can automate dependency updates. Tools like Dependabot or Renovate rely on the MAJOR.MINOR.PATCH signal to decide which updates can merge automatically versus which need manual review, so a project that does not respect SemVer correctly undermines that automation and increases the risk of an unnoticed breaking change reaching production.

Semantic versioning at BeBranded

We apply semantic versioning across the web apps and integrations we build and maintain, so dependency upgrades stay predictable and breaking changes never surprise a client in production.