Skill: avegancafe/semver-helper (version 1.0.1)

--- name: semver-helper description: Semantic Versioning 2.0.0 reference guide. Quick decision trees and examples for choosing MAJOR, MINOR, or PATCH version bumps. author: Gelmir tags: [semver, 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 ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)