What does semantic versioning mean?

Semantic versioning is a scheme that numbers releases as MAJOR.MINOR.PATCH, where MAJOR signals breaking changes, MINOR signals backward-compatible new features, and PATCH signals backward-compatible bug fixes. The number tells consumers how risky an upgrade is before they read the changelog.

When should I bump the major version?

Increment the major version whenever you make an incompatible or breaking change that requires users to modify their code or configuration to keep working. Bumping major resets the minor and patch numbers to zero.

What does the 0 in a 0.x.y version mean?

A leading zero, as in 0.4.2, indicates initial development where the public API is not yet stable. During the 0.x phase, even minor version bumps may introduce breaking changes, so consumers should pin versions carefully.

What is a release candidate version in SemVer?

A release candidate is a pre-release version labeled like v3.0.0-rc.1, meaning it is feature complete and intended to ship as the final version unless a serious bug is found. Pre-release versions have lower precedence than the matching stable version.

Is a security fix a patch or a minor release?

A backward-compatible security fix is a patch release, since it corrects behavior without adding features or breaking compatibility. It is simply a more urgent patch, and the changelog should flag its importance.

Guide

Semantic Versioning (SemVer) Explained Simply

Semantic versioning uses a MAJOR.MINOR.PATCH number where MAJOR means breaking changes, MINOR means backward-compatible features, and PATCH means backward-compatible bug fixes.

Updated 2026-06-30

What is semantic versioning?

Semantic versioning, or SemVer, is a versioning scheme that uses a three-part number in the form MAJOR.MINOR.PATCH, where you increase MAJOR for incompatible breaking changes, MINOR for new features that stay backward compatible, and PATCH for backward-compatible bug fixes. The version number itself communicates how risky an upgrade is before you read a single line of the changelog.

That is the entire promise of SemVer: the number tells you whether an update will break your code. A jump from v2.4.1 to v2.4.2 should be safe, v2.4.1 to v2.5.0 should add features without breaking anything, and v2.4.1 to v3.0.0 warns you that something incompatible changed.

What each number means

Read a SemVer number left to right, from most disruptive to least. Each position has a precise meaning that maintainers commit to honoring.

•MAJOR (the first number): incremented for breaking changes that require the user to take action. Resets MINOR and PATCH to 0.
•MINOR (the second number): incremented for new, backward-compatible features. Resets PATCH to 0.
•PATCH (the third number): incremented for backward-compatible bug fixes only.
•Example: v2.4.0 to v2.5.0 adds features safely; v2.5.0 to v3.0.0 introduces a breaking change.

Pre-release and build labels

SemVer also allows labels appended after the version for releases that are not yet final. A pre-release label follows a hyphen, as in v3.0.0-rc.1 or v3.0.0-beta.2, and signals that the version is unstable and may change before the final release.

Pre-release versions have lower precedence than the normal version, so v3.0.0-rc.1 comes before v3.0.0. This lets you publish release candidates for testing without anyone's tooling treating them as the stable release.

•v3.0.0-alpha.1: early, expect breakage.
•v3.0.0-beta.1: feature complete, still testing.
•v3.0.0-rc.1: release candidate, shipped unless a blocker appears.
•v3.0.0: the stable release.

How SemVer connects to your changelog

Semantic versioning and your changelog are two views of the same information. The changelog explains what changed; the version number summarizes how much it matters. They should always agree.

If your changelog lists a breaking change, the major number must increase. If it lists only features, the minor number increases. If it lists only fixes, the patch number increases. When you use Conventional Commits, tools enforce this link automatically by reading commit types to compute the bump.

Common SemVer questions in practice

A few situations trip people up. Knowing the convention keeps your versioning predictable for the people who depend on it.

•0.x.y versions: anything below 1.0.0 is considered initial development, where even minor bumps may break things.
•Version ranges: dependency managers use carets and tildes, where ^2.4.0 allows minor and patch updates but not a major one.
•Deprecations: deprecating a feature is not itself breaking, but removing it is, so removal requires a major bump.
•Security fixes: a backward-compatible security patch is still a PATCH bump, just a more urgent one.

Why SemVer matters

Semantic versioning is a contract between you and everyone who depends on your software. When you honor it, consumers can upgrade patch and minor versions automatically with confidence and reserve careful attention for major bumps. When you break it, you erode the trust that lets people depend on you at all.

The discipline pays off most in ecosystems, where one library's broken promise about compatibility can cascade through hundreds of downstream projects. Predictable versioning is a small habit with an outsized effect on trust.