Semver Helper

Semantic Versioning 2.0.0 reference guide. Quick decision trees and examples for choosing MAJOR, MINOR, or PATCH version bumps.

Quick reference for Semantic Versioning 2.0.0 decisions.

The Golden Rule

Given version MAJOR.MINOR.PATCH, increment:

Level	Bump When	Reset Lower?
MAJOR (X.0.0)	Breaking changes (incompatible API changes)	Yes, MINOR and PATCH → 0
MINOR (0.X.0)	New features (backwards compatible)	Yes, PATCH → 0
PATCH (0.0.X)	Bug fixes (backwards compatible)	No

Quick Decision Tree

Did you change anything users depend on?
├─ No (internal only) → PATCH
└─ Yes
   └─ Did you remove/change existing behavior?
      ├─ Yes → MAJOR
      └─ No (only added new stuff)
         └─ Is the new stuff visible to users?
            ├─ Yes → MINOR
            └─ No → PATCH

Real Examples

🔴 MAJOR (Breaking)

• Remove a function, endpoint, or CLI flag
• Change the return type of a function
• Require a new mandatory parameter
• Change default behavior significantly
• Rename something users depend on
• Upgrade a dependency that forces downstream changes

Examples:

• removeUser() → deleteUser() rename
• API response format changed from {id: 1} to {data: {id: 1}}
• Dropping support for Node 16 (if users must upgrade)

🟡 MINOR (Feature)

• Add new functionality
• Add optional parameters
• Add new exports/exports
• Deprecate old features (warn, don't remove)
• Performance improvements (no API change)

Examples:

• Add createUser() alongside existing user functions
• Add --format json flag to CLI
• Add new event listeners/hooks
• Mark old method as deprecated (still works)

🟢 PATCH (Fix)

• Fix bugs without changing intended behavior
• Documentation updates
• Internal refactoring (no visible change)
• Dependency updates (no API change)
• Test additions

Examples:

• Fix null pointer exception
• Correct typo in error message
• Fix race condition
• Update README

Version Progression Examples

Changes	Version Bump
fix: null pointer	1.2.3 → 1.2.4
feat: add auth	1.2.3 → 1.3.0
breaking: remove old API	1.2.3 → 2.0.0
fix: bug + feat: new thing	1.2.3 → 1.3.0 (MINOR wins)
fix: bug + breaking: remove API	1.2.3 → 2.0.0 (MAJOR wins)

Pre-releases

Use suffixes for testing before stable:

• 2.0.0-alpha.1 — Very early, unstable
• 2.0.0-beta.2 — Feature complete, testing
• 2.0.0-rc.1 — Release candidate, final testing

Pre-releases sort before their stable version: 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc < 1.0.0

Common Edge Cases

Situation	Bump	Why
Fix a bug that was introduced this version	PATCH	Still a fix
Deprecate a feature (but keep it working)	MINOR	New "deprecated" state is info
Change undocumented/internal behavior	PATCH	Users shouldn't depend on it
Security fix that requires API change	MAJOR	Breaking for security
Rewriting internals, same behavior	PATCH	Invisible to users
Adding tests/docs only	PATCH	No code change

Anti-Patterns

❌ Don't bump MAJOR for big new features (unless breaking) ❌ Don't bump MINOR for bug fixes ❌ Don't bump PATCH for new functionality ❌ Don't keep old numbers when bumping: 1.2.3 → 2.2.3 is wrong

Cheat Sheet

Users' code breaks? → MAJOR
Users get new toys? → MINOR
Users get fixes? → PATCH