Semver Helper

Quick reference for Semantic Versioning 2.0.0 decisions.

The Golden Rule

Given version MAJOR.MINOR.PATCH, increment:

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

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

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