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:...