# Semver Helper

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

- Skill: `modbender/semver-helper` (Agent Skill)
- Install (CLI): `npx skillmds@latest add modbender/semver-helper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/semver-helper/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/semver-helper

---


# 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
```