Semantic Versioning (SemVer) Explained

What is Semantic Versioning?

Semantic Versioning (SemVer) is a versioning convention that communicates meaning about the underlying changes. Every version number has three parts:

MAJOR.MINOR.PATCH
  3  .  2  .  1

The three parts

• MAJOR (3.x.x) — Breaking changes. Existing integrations may need updates.
• MINOR (x.2.x) — New features that are backward-compatible. Safe to upgrade.
• PATCH (x.x.1) — Bug fixes and minor improvements. No new features, no breaking changes.

When to bump what

Here are typical scenarios:

1.0.0 → 1.0.1  Bug fix (patch)
1.0.1 → 1.1.0  New feature (minor)
1.1.0 → 2.0.0  Breaking change (major)

Pre-release versions

SemVer supports pre-release labels for testing:

2.0.0-alpha.1
2.0.0-beta.3
2.0.0-rc.1

Why SemVer matters

• It communicates the risk of an upgrade at a glance.
• Package managers (npm, Composer) use it for dependency resolution.
• It builds trust: users know what to expect from each release.
• It prevents dependency hell in complex projects.

SemVer and changelogs

A changelog organized by SemVer versions gives users a clear upgrade path. Each version entry tells them exactly what changed and whether they need to take action. Tools like Deplyd automatically display version numbers alongside your changelog entries.