Semantic Versioning Explained

Semantic Versioning, often shortened to SemVer, is a version-numbering system that uses MAJOR.MINOR.PATCH to communicate compatibility expectations. In the SemVer specification, those numbers matter only when the project defines a public API.

The short rule is: increment MAJOR for incompatible API changes, MINOR for backward-compatible functionality, and PATCH for backward-compatible bug fixes. That rule helps users estimate upgrade risk, but it does not prove that an upgrade is safe for every project or environment.

The MAJOR.MINOR.PATCH pattern

A SemVer version has three required numeric parts:

• MAJOR: incompatible public API changes;
• MINOR: backward-compatible added functionality;
• PATCH: backward-compatible bug fixes.

For example, a change from 2.3.4 to 2.3.5 suggests a patch release. A change from 2.3.4 to 2.4.0 suggests backward-compatible added functionality. A change from 2.3.4 to 3.0.0 signals incompatible public API changes.

The important word is suggests. SemVer is a convention backed by a specification, but projects still need to apply it correctly and document what their public API includes.

Public API is the foundation

Semantic Versioning depends on a public API. For a library, that may mean exported functions, classes, command behavior, configuration files, data formats, extension points, or documented interfaces. For a command-line tool, it may include flags, output formats, exit codes, and config behavior.

If a project does not define its public API, version numbers become harder to trust. A maintainer may consider an internal file format private while users have built automation around it. A user may expect command output to remain stable while maintainers see it as human-readable text that can change.

Before relying on SemVer, check the documentation for what the project treats as public, stable, experimental, or internal.

What counts as a breaking change

A breaking change is a change that can make existing supported use fail when users upgrade. It may remove a function, change expected input, alter output shape, rename a command, drop a platform, change a file format, or require a migration step.

Breaking changes are not always bad. They may fix design mistakes, remove insecure behavior, simplify maintenance, or prepare the project for future work. SemVer's value is that the major version number tells users to expect the possibility of incompatibility.

Some changes are ambiguous. A bug fix can break users who depended on the bug. A performance change can affect timing-sensitive workflows. A dependency update can change behavior outside the project's direct API. Good release notes explain the real risk rather than relying only on the version number.

Prerelease labels and build metadata

SemVer supports prerelease labels such as 1.4.0-alpha.1, 1.4.0-beta.2, or 1.4.0-rc.1. These identify versions that come before a normal release and may have different stability expectations.

Build metadata can appear after a plus sign, such as 1.4.0+build.27. The SemVer specification defines how this metadata relates to version precedence, but users should still read project documentation because package managers and ecosystems may display or handle metadata differently.

Prerelease labels are useful when maintainers want testing before a stable release. Users should treat them as signals to read the release notes and avoid assuming production stability unless the project explicitly says otherwise.

Version changes and user action

This table is a practical reading aid, not a substitute for the official specification or project release notes.

SemVer in open source releases

SemVer helps open source maintainers communicate with users they may never meet. Package maintainers, downstream distributions, plugin authors, and application teams can all use version numbers as an early risk signal.

It also helps contributors understand the impact of a change. A pull request that alters documented behavior may need to wait for a major release. A compatible feature may belong in a minor release. A small fix may be safe for a patch line.

The convention works best when paired with changelogs, migration notes, tests, and a clear release process. Version numbers should point readers to the right level of attention; they should not carry the whole communication burden.

Where SemVer does not fit cleanly

Semantic Versioning is less helpful when a project has no defined public API, ships only a hosted service, changes content rather than behavior, uses date-based releases, or treats every release as a complete product snapshot.

Desktop applications can use SemVer, but the public API may be less obvious than in a library. Users may care about file compatibility, plugin compatibility, settings migration, command-line options, or extension APIs. The project should say which of those are covered.

Some ecosystems use version ranges and dependency resolution rules that build on SemVer. Those ecosystem rules are separate from the SemVer specification. Do not assume every package manager handles ranges, prereleases, or metadata in the same way.

Checklist for maintainers and users

Maintainers should check:

1. The public API is documented.
2. Breaking changes are labeled as major releases.
3. Backward-compatible features use minor releases.
4. Backward-compatible fixes use patch releases.
5. Prerelease labels clearly signal stability expectations.
6. Release notes explain migration, compatibility, and known risks.

Users should check:

1. The project says it follows SemVer.
2. The public API includes the behavior they rely on.
3. The release notes match the version bump.
4. Major upgrades are tested before important workflows move.
5. Prereleases are treated as test candidates unless documented otherwise.

Semantic Versioning is useful because it turns version numbers into a compact compatibility signal. It is strongest when projects define the public API honestly and users still read the release notes before high-risk upgrades.