The Practical Developer

Semantic Versioning In Practice: Why Your Patches Keep Breaking Your Users

March 31, 2023 by The Practical Developer

SemVer is simple on paper and dishonest in practice. Most maintainers ship breaking changes in patches and call it "a bug fix." Here is what each version part actually means, the four kinds of changes that look like patches but aren't, and the deprecation playbook that lets you evolve a public API without breaking the world.

process

tools

productivity

Train tracks splitting — the visual that always shows up next to a versioning post for a reason

Your team’s package gets a 1.4.7 patch release. Twenty minutes later, three downstream apps are broken. The release notes say “fixed a typo in error message.” The “typo” was changing the message string — which one of the consumers was matching against in a test. The PR was approved, the patch was published, and you have done exactly what every unhappy upstream maintainer does: you shipped a breaking change in a patch version.

SemVer is the convention everybody claims to follow and almost nobody actually does. The reason is not laziness — it is that “what counts as breaking” is hard, and the incentive structure rewards under-numbering. This post is the operational version: the four ways a “patch” can break consumers, the rules that hold up in practice, and the deprecation playbook that lets you change anything you want without renaming the package.

What MAJOR.MINOR.PATCH actually means

The simple version everybody knows:

  • MAJOR — breaking changes.
  • MINOR — new features, backwards-compatible.
  • PATCH — bug fixes, no API change.

The more honest version:

  • MAJOR — anything that requires consumers to change any code or configuration to upgrade.
  • MINOR — anything that adds capability without requiring changes.
  • PATCH — anything that only changes implementation, not observable behavior.

The middle row is where most disagreement lives. A new optional method on a class is minor. A new required method is major (subclasses break). A new optional parameter at the end of a function signature is minor in some languages, major in others.

Four “patches” that break consumers

If you have shipped any of these as a patch, you have shipped a breaking change.

1. Changing an error message. Consumers may match on the string. Rare? Less than you think — every test that asserts an error message will break. Either keep the old message or bump major.

2. Tightening validation. “We were accepting empty strings; we now reject them” sounds like a fix. To consumers passing an empty string, it is a regression. Either keep accepting and add a new strict mode, or bump major.

3. Removing a deprecated feature. Deprecated does not mean removed; the feature still works. Removing it requires a major bump even if you have shouted about deprecation for a year.

4. Performance regression that changes behavior. A “fix” that adds an extra round trip changes timing. Consumers depending on the old timing (test mocks, race-prone code) break. Document timing changes; if they could break consumers, bump minor at least.

The rule of thumb: if a consumer would have to change anything — a string, a config, a test — to upgrade cleanly, it is not a patch.

The categories of breaking change

These all warrant a major bump:

  • Removing or renaming a public API.
  • Changing the type of a parameter or return.
  • Changing the meaning of an existing parameter (e.g., timeoutMs becomes timeoutSec).
  • Removing support for a runtime, OS, or language version.
  • Changing default values for options.
  • Changing observable behavior (timing, ordering, errors thrown).
  • Removing exported types or interfaces.
  • Changing the package’s module shape (CJS → ESM, default vs named export).

That last one is the trap nobody warns about. Switching from CommonJS to ESM is a major break even though no API “changed” — every consumer’s import statement breaks.

The deprecation playbook

When you need to change something, the path is add-new → deprecate-old → remove-old. Three releases minimum.

Release N (minor): add the new way.

// Old API stays.
export function fetchUser(id: string) { ... }

// New API alongside.
export function getUser(id: string, opts?: { include?: string[] }) { ... }

Both work. Existing code is fine.

Release N+1 (minor): mark the old way deprecated.

/**
 * @deprecated Use getUser instead. Will be removed in v2.0.
 */
export function fetchUser(id: string) {
  if (process.env.NODE_ENV !== 'production') {
    console.warn('fetchUser is deprecated. Use getUser instead.');
  }
  return getUser(id);
}

The TS @deprecated JSDoc tag puts a strikethrough in IDEs. The runtime warning ensures nobody misses it. Crucially, the function still works.

Release N+M (major, after a long enough window): remove the old way.

// fetchUser is gone.

Consumers who paid attention to the deprecation warning have already migrated. Consumers who did not get a clear error: “fetchUser is not a function.” They can read the changelog and migrate.

The window between deprecation and removal depends on your audience. Six to twelve months is typical for libraries with hundreds of consumers. For internal packages with a known set of consumers, a few weeks is enough — coordinate with them.

Communicating breaking changes

A CHANGELOG.md that follows keep-a-changelog format is the minimum. Group changes:

## [2.0.0] - 2023-03-15

### Breaking
- Removed `fetchUser` (deprecated since 1.4). Use `getUser` instead.
- Changed default timeout from 30s to 5s. Pass `{ timeout: 30_000 }` to restore.

### Added
- `getUser` accepts an `include` option for related entities.

### Fixed
- Connection pool not draining on `close()`.

### Migration
- Replace `fetchUser(id)` with `getUser(id)`.
- Audit code that relied on the 30s default; explicitly pass `timeout` if needed.

The Migration section is the one that matters most. Every breaking change should answer “what does the consumer have to do to upgrade?” If you cannot answer that in two sentences per change, the change is too big.

SemVer in package managers

Both npm and pip use semantic version ranges. Defaults:

"^1.4.0"  // npm: >=1.4.0 <2.0.0 — accept any 1.x
"~1.4.0"  // npm: >=1.4.0 <1.5.0 — accept patches only
">=1.4"   // pip: similar

The default of ^ (“compatible release”) is correct if you trust the upstream’s SemVer discipline. For a library that ships breaking changes in minors regularly (looking at every popular framework), pin tighter — ~1.4.0 or even an exact version.

Lockfiles (package-lock.json, Pipfile.lock) protect you from upstream surprises between installs. Run npm ci (clean install from lockfile) in CI, not npm install, so a maintainer’s bad publish does not silently change your build.

Pre-1.0 has different rules

Versions below 1.0 (0.x.y) are explicitly “anything can change.” The npm convention treats 0.x as MAJOR — 0.5.1 to 0.6.0 is a breaking-change range.

Push to 1.0 sooner rather than later. Sitting at 0.x forever is mostly an excuse to keep breaking consumers without bumping major. If your library is being used in production, it is 1.0; act like it.

Conventional commits → automatic versioning

If your commit messages follow conventional commits format, you can automate version bumps:

feat: add getUser()              → minor bump
fix: connection pool drain bug   → patch bump
feat!: remove fetchUser           → major bump (the ! marks breaking)
BREAKING CHANGE: ...              → major bump (in body)

Tools like release-please and semantic-release read your commit history, decide the bump, generate the changelog, and publish — all from CI on merge to main. Adopt this once your release cadence is faster than once a quarter.

A side effect: writing feat!: requires you to think about whether the change is breaking before you commit it. That single habit is worth the tooling.

When NOT to follow SemVer

SemVer is a convention, not a religion. Two cases where strict SemVer hurts:

Application versions. Your customer-facing app does not need SemVer; bump as makes sense (year-based, sprint-based, feature-named). SemVer is for libraries with consumers.

Pre-release / dev / nightly. Use the pre-release suffix: 2.0.0-alpha.4, 2.0.0-rc.1. These do not satisfy ^2.0.0 ranges, which is exactly right.

For everything else — public packages, internal libraries with multiple consumers, anything you npm publish — the discipline pays for itself the first time someone successfully runs npm update and nothing breaks.

The takeaway

SemVer is hard because “what is a breaking change” is harder than the spec implies. The default is to bump bigger, not smaller — the cost of a too-small bump (a downstream user pinning to a specific version forever) is worse than a too-big one (a major bump that nobody minds).

Add the deprecation cycle to your process. Write a migration line in the changelog for every breaking change. Use conventional commits to make versioning automatic and to force you to label breakage at commit time. The next time someone asks “should this be a patch or a minor,” the answer is whichever forces you to write the migration note.

A note from Yojji

The kind of release-engineering discipline that turns “we shipped 1.4.7” from a guessing game into a routine — conventional commits, deprecation cycles, automated release notes — is the kind of long-haul engineering Yojji’s teams build into the libraries and platforms they ship for clients.

Yojji is an international custom software development company founded in 2016, with teams in Europe, the US, and the UK. They specialize in the JavaScript ecosystem, cloud platforms (AWS, Azure, GCP), and full-cycle product engineering — including the release process and versioning practices that decide whether downstream consumers can upgrade safely.