0x55aa
ā† Back to Blog

Semantic Versioning: The Promise That Keeps a Million npm Packages From Exploding šŸ’„šŸ“¦

ā€¢11 min read
"open-source""github""semver""developer-tools""community"

Semantic Versioning: The Promise That Keeps a Million npm Packages From Exploding šŸ’„šŸ“¦

True story: Three years into my career, I updated a dependency from 2.3.1 to 2.4.0.

Minor version bump. Should be safe, right? No breaking changes?

Wrong. My staging environment combusted. The login page threw 500 errors. Users couldn't authenticate. My on-call weekend was ruined by what a package maintainer called a "minor enhancement." šŸ”„

That was the day I stopped treating version numbers as arbitrary digits and started understanding them as promises.

What Even Is Semantic Versioning? šŸ¤”

Semantic versioning ā€” SemVer for short ā€” is a versioning scheme that looks like this:

MAJOR.MINOR.PATCH
  2  .  4  .  1

But it's not just a format. It's a contract with every developer who depends on your code:

PATCH (2.4.1 ā†’ 2.4.2): "I fixed a bug. Nothing will break."
MINOR (2.4.1 ā†’ 2.5.0): "I added features. Old code still works."
MAJOR (2.4.1 ā†’ 3.0.0): "I changed stuff. Update your code."

Three numbers. Three commitments. One of the most important conventions in all of software development ā€” and most developers only half understand it.

As a full-time developer who contributes to open source, I've been on both sides of bad versioning. As a consumer: rage-updating broken dependencies at midnight. As a contributor: nervously deciding whether a PR I merged deserved a minor or major bump.

Both experiences changed how I think about code.

The Anatomy of a Version Bump šŸ”¬

Let me break down what each number ACTUALLY means in practice.

PATCH ā€” The "Oops, I Fixed It" Number šŸ©¹

1.2.3 ā†’ 1.2.4

Safe to upgrade. Always. No exceptions.

A patch release means:

  • Bug was fixed
  • Security vulnerability patched
  • Typo corrected in error message
  • Performance improvement with no API changes

In the Laravel community, we wait for patch releases the way people wait for firmware updates on a new router ā€” eagerly and without fear. laravel/framework 11.x.1 to 11.x.2? Merge it immediately. That's a bug fix.

My rule: Patch updates go into production same day. Automated. No review needed. That's the whole point.

MINOR ā€” The "I Made It Better" Number āœØ

1.2.3 ā†’ 1.3.0

Backwards-compatible additions. Your existing code should still work.

A minor release means:

  • New methods or functions added
  • New optional parameters added
  • New configuration options added (with sensible defaults)
  • Deprecation warnings added (but old behavior still works)

Example from real life:

// Before minor bump: 1.2.x
$client->sendRequest($url, $data);

// After minor bump: 1.3.0 (new optional parameter added)
$client->sendRequest($url, $data, $timeout);
// Old call still works! āœ… New optional param doesn't break anything

The catch: Minor releases are where bad maintainers hide breaking changes and call them "enhancements." šŸ˜¤

That weekend incident I mentioned? The 2.3.x ā†’ 2.4.0 bump that broke auth? The maintainer added a new required config key and called it a "minor feature addition." It was not minor. It was chaos wearing a minor version hat. šŸŽ­

MAJOR ā€” The "Buckle Up" Number šŸšØ

1.2.3 ā†’ 2.0.0

Breaking changes. Read the migration guide. Allocate time.

A major release means:

  • Methods renamed or removed
  • Function signatures changed (required parameters added)
  • Return types changed
  • Configuration format completely overhauled
  • Entire architectural approach rethought

Laravel 10 ā†’ 11 is a perfect example:

// Laravel 10: app/Http/Kernel.php existed
// Laravel 11: no Kernel.php - bootstrapping completely changed

// If you upgraded without reading the docs... pain. šŸ’€

But here's the thing: Major version bumps are actually an act of respect. When a maintainer bumps from v1 to v2, they're saying: "We have to change the contract. Here's fair warning. Here's a migration guide. We're not going to pretend these changes are invisible."

Balancing work and open source taught me: A major bump with a great migration guide is better than a minor bump that silently breaks things. Version numbers are communication tools.

The SemVer Rules Nobody Tells You About šŸ•µļø

Rule 1: Version 0.x.x is the Wild West

0.1.0, 0.2.0, 0.9.0 ā€” anything goes!

When a project is on 0.x.y, all bets are off. Breaking changes can happen in any release. SemVer explicitly says that 0.x.y is for initial development.

Translation: Don't build production systems on 0.x.y dependencies unless you're prepared for chaos.

# I've made this mistake
npm install [email protected]
# Three weeks later:
# "0.9.0 released! We refactored everything!"
# *every import breaks*
# Me: šŸ™ƒ

Rule 2: Once Released, Never Rewrite

SemVer's golden rule: once a version is published, never modify it.

If you discover a bug in 2.3.1 after publishing it, you don't fix 2.3.1. You release 2.3.2 with the fix.

This sounds obvious until you're a panicked first-time maintainer who realizes you published broken code at 11pm and just wants to "quickly fix the file on npm."

Don't. Release 2.3.2. Move on.

Rule 3: Pre-releases Are Their Own World

1.0.0-alpha.1
1.0.0-beta.3
1.0.0-rc.1
1.0.0

Pre-release versions signal "this might break." They sort below the stable version. They're for testing.

In the Node.js ecosystem, I use this constantly:

# Want to test upcoming changes without breaking prod?
npm install my-package@beta

# Back to stable:
npm install my-package@latest

How Semver Saved (and Wrecked) My Open Source Contributions šŸŽ¢

The Save šŸ’š

Early in my open source journey, I made a PR to a PHP security library that changed how the config was parsed. The maintainer ran me through something I hadn't considered:

"Is this backwards-compatible?"

I thought about it. If existing users had config.php files structured the old way, my change would break them silently. The maintainer helped me redesign the PR: new format supported, old format still works, deprecation notice added.

Result: MINOR bump, not MAJOR. Zero breakage for existing users. Clean migration path.

That review taught me more about API design than years of solo projects. Open source code review is basically free education if you pay attention.

The Wreck šŸ˜µ

A year later, I submitted a PR to a Node.js library I used heavily. I was confident. I'd done the homework. The PR was accepted.

And then I bumped the wrong number. We agreed it was a minor release. I updated the CHANGELOG. Maintainer published it.

But I had introduced a subtle breaking change I hadn't caught. An optional parameter that became required in an edge case. Three users opened issues within 48 hours.

We had to release a hotfix (patch bump) and update the CHANGELOG with a "despite the minor version, if you use X feature, see migration notes."

I felt terrible. Those three users had followed the contract in good faith. A minor version shouldn't have required migration notes.

Lesson learned: Before bumping any version, ask yourself: "If a user runs this update automatically, will ANYTHING break?"

The Semver Toolchain You Should Know About šŸ› ļø

For Node.js projects: semantic-release

npm install semantic-release --save-dev

This tool reads your conventional commit messages and automatically determines the next version:

feat: add new authentication method    ā†’ MINOR bump
fix: resolve null pointer in parser    ā†’ PATCH bump
feat!: redesign entire API             ā†’ MAJOR bump

It also generates your CHANGELOG and creates GitHub releases automatically. It's like removing the human error from versioning entirely.

I've set this up in three projects and it's one of those tools where you wonder how you lived without it.

For PHP/Composer projects: Check composer.json constraints

{
  "require": {
    "vendor/package": "^2.4",
    "another/pkg": "~1.3.0"
  }
}

^2.4 means: "2.4.x and above, but NOT 3.x" (allows minor and patch updates)

~1.3.0 means: "1.3.x only" (allows only patch updates)

>=2.4 <3.0 means: "explicitly between these versions" (most explicit)

In the security community, we often pin to ~ or exact versions for critical dependencies. The attack surface of automated dependency updates is real ā€” ^ is convenient right up until a compromised minor release lands in your production app.

GitHub's Dependabot: Automation + Control

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Only auto-merge patch updates
    open-pull-requests-limit: 10

Dependabot opens PRs when versions update. You review before merging. Patch updates? Auto-merge them in CI. Minor? Quick review. Major? Allocate time, read the changelog, test carefully.

The goal: treat SemVer's promises as real signals, not noise to click through.

When Maintainers Break the Contract šŸšØ

Here's what nobody talks about enough: SemVer is only as useful as the maintainer's discipline.

The npm ecosystem is full of "minor" releases that break things. I've been personally victimized by:

  • Optional parameters becoming required (breaking)
  • Internal behavior changes that users depended on (technically not a public API, but still)
  • Silent removal of a feature "nobody used" (they were wrong)
  • Config format changes "for clarity" (in a minor release, meaning users found out at runtime)

How do you protect yourself?

# Check the CHANGELOG before upgrading any package
# Most maintainers who break semver don't announce it loudly
# But the GitHub diff doesn't lie

# Before upgrading:
git diff HEAD package-lock.json  # after npm update
# Then check the actual changes before committing

In the security community, we also watch for version bumps that correspond with CVE disclosures. Sometimes a "patch" update fixes a vulnerability and the release notes are deliberately vague. Look at the actual diff, not just the commit message.

How to Version YOUR Open Source Project Right šŸ“‹

If you're maintaining (or planning to maintain) an open source library, here's the checklist I follow:

Before any release:

ā–” Does this change any existing public API?
  ā†’ Yes: it's at least MINOR, check if it's MAJOR
ā–” Does this remove or rename anything?
  ā†’ MAJOR. No exceptions.
ā–” Does this add required parameters to existing functions?
  ā†’ MAJOR. No exceptions.
ā–” Does this add optional features without changing existing behavior?
  ā†’ MINOR
ā–” Does this fix bugs or patch security issues?
  ā†’ PATCH
ā–” Is my CHANGELOG updated with what actually changed?
  ā†’ Not optional
ā–” Have I tested that existing user code still works?
  ā†’ Not optional

The CHANGELOG reality check:

## [2.4.0] - 2026-02-20
### Added
- `sendWithTimeout()` method for configurable request timeouts
- New `retry_count` configuration option (defaults to 3)

### Fixed
- Memory leak in connection pool when requests fail (closes #247)

## [2.3.2] - 2026-02-15
### Fixed
- Null pointer exception when response body is empty (closes #241)

Short. Specific. Honest. Users should be able to read this and know immediately whether they need to change their code.

The Bigger Picture: Why This Actually Matters šŸŒ

The npm registry has over 2 million packages. Composer has 400,000. Packagist processes billions of dependency resolutions every year.

The entire thing works because of a shared agreement: SemVer.

When a package says ^3.2.1, the package manager trusts the maintainer kept their promise. When you run composer update in production and nothing explodes, that's SemVer working as intended. That's thousands of maintainers, across millions of packages, honoring a social contract.

It's genuinely impressive. And genuinely fragile.

Every time a maintainer slips a breaking change into a minor version, they're eroding trust ā€” not just in their package, but in the convention everyone depends on.

As a full-time developer who contributes to open source, I take this seriously. Bumping a MAJOR version feels like a heavy decision. It should. It means asking users to do work. It means they'll probably postpone the upgrade. It means your project shows up in people's "outdated major versions" lists.

But it's the right thing to do. Hiding breaking changes in minor versions feels like a shortcut. It's actually a debt you pay in trust.

TL;DR ā€” The Version Number Is a Promise šŸ“‹

  1. PATCH = bug fixes only. Auto-upgrade these.
  2. MINOR = new features, backwards-compatible. Spot-check before upgrading.
  3. MAJOR = breaking changes. Read the migration guide. Allocate time.
  4. 0.x.y = early development. Expect chaos.
  5. Tools to know: semantic-release (Node.js), Dependabot, conventional commits
  6. As a maintainer: honor the contract. Your users are counting on those numbers to mean something.

That login page I broke three years ago? I eventually tracked down the maintainer. Turned out they knew it was a breaking change and shipped it as a minor to "avoid scaring users away from upgrading."

The irony: the breaking minor release scared people away way more effectively than a well-documented major bump ever would have.

Version numbers are communication. Use them honestly. šŸ¤

Using SemVer properly in your projects? Share your versioning horror stories with me on LinkedIn or GitHub ā€” I want to hear the "minor bump that wasn't" stories. We all have them. šŸ˜…

What's your current dependency upgrade strategy? Let's talk versioning in the comments!

ā† Back to all posts