Section: languages-frameworks
Kind: Editorial
Reading time: 3 min
Updated: 8 September 2026

When Is a Major Version Bump Truly a Major Version Bump?

Semantic Versioning promises that software users can plan ahead for breaking changes. But the schemes baked into cloud ecosystems, package managers, and documentation APIs are neither always consistent, nor comprehensive. Maintainers have to act on the gaps — and not all agree what consistency means.

What SemVer Actually Requires

Semantic Versioning (SemVer) 2.0.0 formally defines how software maintainers must disclose breaking changes and upgrades:

Software must declare a public API.
Releases must follow X.Y.Z versioning. URL: semver.org/spec/v2.0.0-rc.2.html ]
X, Y, and Z must increase by 1 when a version is bumped.

Pre-release and metadata tags can follow the patch, Y, or Z, but do not force a major.

What Major Means in Package Ecosystems

In npm, publishers and maintainers are expected to bump the major number for any public API change that breaks backward compatibility.¹

This isn't the same as breaking compile-time references to an internal API or data structure, which the SemVer spec groups under "the public API":

The system boundary is the contract between two publishing "teams", as distinct from the maintainers of libraries against which Semver is synced.
npm's catalog tends to group many teams under a single API boundary, but Semver says maintainers must clarify what's included and who it's meant for.

Pre-Release and Metadata Are Not the Same Thing

Much of the confusion in the versioning scheme hinges on the fact that "beta" and "RC" labels, and the "+" suffix used for build metadata, are added to the main version string.

Note:

You must append a hyphen after Y or Z for a pre-release tag, e.g. 1.0.0-alpha.
You must append a "+" at Y or Z for build metadata, e.g. 1.0.0+exp.sha.5114f85.

Build metadata is only decorative: it has no effect on whether prerelease tags are numerically lower or higher than the base version, so they can't be used interchangeably.

What Still Needs Verification Before the Release

There are still many open questions about how major version bumps should be calculated, and what maintainers can keep inside a major-version umbrella. Documentation is sparse or contradictory, and neither npm Docs nor the SemVer spec answer all of the following:

To call something a major release, should every concurrent bump on every consumer API be considered a breaking change? Libraries are built up of many small modules labeled with incrementing versions of their own.
If a bump on a library's shared dependency leaks into user-facing APIs, should it be a major version too? An audit workflow here could lower support load on maintainers.
How long after a major bump should deprecated APIs be supported, to give dependent maintainers and users a reasonable time to migrate? Timing advice has not been verified.
Should there be a prescribed method for ensuring bumped packages remain secure, or for maintaining package lines? Support practices vary widely.
What exactly does the changelog entry for a major release need to contain, and where in the file? Clear notation could eliminate many dependency-migration questions beforehand.

The SemVer specification itself does not answer those questions — it defines only API boundaries, version numbering, and-- the syntax around pre-release and build metadata. All of the above involve policies, which the specification and documentation do not establish.

Only the npm documentation has established guidelines on versioning behavior, even though it only covers their own ecosystem — programmers using different toolchains may not get the same guarantees.

Sources

npm Docs