semver-helper

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

$ git log --oneline --stat

stars:1,933

forks:367

updated:March 4, 2026

SKILL.mdreadonly

SKILL.md Frontmatter

namesemver-helper

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

authorGelmir

tagssemver,versioning,release

Semver Helper

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