Semantic Version Advisor

This skill helps classify version changes, determine appropriate version bumps, and validate semantic versioning decisions.

Quick Reference

Version Format: MAJOR.MINOR.PATCH

• •MAJOR: Breaking changes, incompatible API changes
• •MINOR: New features, backward-compatible additions
• •PATCH: Bug fixes, backward-compatible fixes

Core Workflows

Workflow 1: Classify Version Change

Input: Old version and new version Output: Classification (MAJOR/MINOR/PATCH) with explanation

Decision Tree

┌─────────────────────────────────┐
│  Compare versions X.Y.Z         │
└────────────┬────────────────────┘
             │
             v
    ┌────────────────┐
    │ X changed?     │─ YES ──> MAJOR (breaking changes)
    └────┬───────────┘
         │ NO
         v
    ┌────────────────┐
    │ Y changed?     │─ YES ──> MINOR (new features)
    └────┬───────────┘
         │ NO
         v
    ┌────────────────┐
    │ Z changed?     │─ YES ──> PATCH (bug fixes)
    └────┬───────────┘
         │ NO
         v
    Same version

Classification Steps

1. •Parse versions: Extract MAJOR.MINOR.PATCH from both versions
2. •Strip notation: Remove ^, ~, >= prefixes if present
3. •Compare MAJOR: If different → MAJOR change
4. •Compare MINOR: If different → MINOR change
5. •Compare PATCH: If different → PATCH change
6. •Verify: Confirm classification matches change type

Examples

^4.0.0 → ^5.0.0     = MAJOR (4 → 5, breaking changes)
^13.1.5 → ^13.2.0   = MINOR (1 → 2, new features)
^7.1.5 → ^7.1.6     = PATCH (5 → 6, bug fixes)
9.35.0 → 9.36.0     = MINOR (35 → 36, new features)
1.0.0 → 1.0.1       = PATCH (0 → 1, bug fixes)

Workflow 2: Determine Version Bump

Input: List of changes to be included in release Output: Recommended version bump (MAJOR/MINOR/PATCH)

Change Classification

MAJOR bump required if ANY of:

• •Breaking API changes (removed methods, changed signatures)
• •Incompatible behavior changes
• •Removed public APIs or interfaces
• •Changed default behaviors that break existing code
• •Renamed public modules or packages
• •Dropped support for language/runtime versions

MINOR bump required if ANY of:

• •New features or capabilities added
• •New APIs or methods added
• •New optional parameters added
• •Deprecated APIs (but still functional)
• •Performance improvements (non-breaking)
• •New dependencies added

PATCH bump if ALL of:

• •Bug fixes only
• •Documentation updates
• •Internal refactoring (no API changes)
• •Security patches (backward-compatible)
• •Test improvements
• •Build process changes

Decision Process

Start with PATCH (default)
  ↓
For each change:
  - Breaking change? → Upgrade to MAJOR, stop
  - New feature? → Upgrade to MINOR, continue
  - Bug fix? → Keep current level, continue
  ↓
Return highest level encountered

Example Analysis

Changes:

• •Fixed null pointer exception in getData()
• •Added new fetchAsync() method
• •Updated documentation

Analysis:

1. •Null pointer fix → PATCH candidate
2. •New method → MINOR upgrade (overrides PATCH)
3. •Documentation → No impact

Result: MINOR bump (new functionality added)

Workflow 3: Validate Version Proposal

Input: Current version, proposed version, change list Output: Validation result (valid/invalid) with reasoning

Validation Rules

1. •Version must increase: New version > current version
2. •Only one segment increases: Increment MAJOR OR MINOR OR PATCH
3. •Reset lower segments: When incrementing, reset lower segments to 0
   • •MAJOR bump: 1.5.3 → 2.0.0 ✅ (MINOR and PATCH reset)
   • •MINOR bump: 1.5.3 → 1.6.0 ✅ (PATCH reset)
   • •PATCH bump: 1.5.3 → 1.5.4 ✅ (no reset needed)
4. •Match change severity: Version bump matches most severe change
   • •Breaking change → MAJOR required
   • •New feature → MINOR minimum
   • •Bug fix only → PATCH appropriate

Validation Examples

Valid:

• •1.2.3 → 2.0.0 with breaking changes ✅
• •1.2.3 → 1.3.0 with new features ✅
• •1.2.3 → 1.2.4 with bug fixes ✅

Invalid:

• •1.2.3 → 1.4.0 (skipped MINOR version) ❌
• •1.2.3 → 2.1.0 (MINOR not reset to 0) ❌
• •1.2.3 → 1.2.3 (no change) ❌
• •1.2.3 → 1.3.0 with breaking changes (under-versioned) ❌
• •1.2.3 → 2.0.0 with only bug fixes (over-versioned) ❌

Common Pitfalls

❌ Misclassifying Range Notation

Wrong: ^7.1.5 → ^7.1.6 = "Major" because of the caret Right: ^7.1.5 → ^7.1.6 = PATCH (ignore the ^, compare numbers)

❌ Assuming Package Importance

Wrong: Core package changed → must be MAJOR Right: Classify by version numbers, not package importance

❌ Ignoring Reset Rules

Wrong: 1.5.3 → 2.1.0 for MAJOR bump Right: 1.5.3 → 2.0.0 for MAJOR bump (reset MINOR and PATCH)

❌ Security Assumptions

Wrong: Security fix → must be PATCH Right: Security fixes can be any level (breaking fix = MAJOR)

Pre-release Versions

Format

• •1.0.0-alpha.1 - Alpha pre-release
• •1.0.0-beta.2 - Beta pre-release
• •1.0.0-rc.1 - Release candidate

Precedence

1.0.0-alpha.1
  < 1.0.0-alpha.beta
  < 1.0.0-beta
  < 1.0.0-beta.2
  < 1.0.0-rc.1
  < 1.0.0

Pre-release Classification

• •1.0.0 → 1.0.0-alpha.1 = Pre-release (no semver bump)
• •1.0.0-beta.1 → 1.0.0 = Release (no semver change)
• •1.0.0-rc.1 → 1.1.0 = MINOR release from RC

Research Depth by Type

MAJOR Version Changes

Required Research:

• •Full changelog review
• •Breaking change analysis
• •Migration guide review
• •API compatibility check
• •Test coverage verification

Time Investment: High (30-60 minutes)

MINOR Version Changes

Required Research:

• •Feature overview
• •Deprecated API checks
• •New dependency review
• •High-level compatibility check

Time Investment: Medium (10-20 minutes)

PATCH Version Changes

Required Research:

• •Security advisory check only
• •Skip detailed changelog review

Time Investment: Low (2-5 minutes)

Integration with Other Tools

NPM/Yarn Commands

# View outdated packages with version info
npm outdated

# Machine-readable upgrade information
npx ncu --jsonUpgraded

# Yarn version check
yarn outdated

Semver Utility Commands

# Classify version difference
semver diff 1.2.3 1.3.0  # Output: "minor"

# Compare versions
semver gt 1.3.0 1.2.3    # Output: true

# Check range satisfaction
semver satisfies 1.2.4 "^1.2.3"  # Output: true

Advisory Templates

Template: Version Bump Recommendation

**Recommended Version Bump**: [MAJOR/MINOR/PATCH]

**Current Version**: X.Y.Z
**Proposed Version**: A.B.C

**Change Summary**:

- [Breaking/Feature/Fix]: Description

**Reasoning**:
[Explain why this classification based on change types]

**Migration Notes** (if MAJOR):
[Required steps for consumers]

Template: Dependency Update Classification

**Package**: package-name
**Version Change**: X.Y.Z → A.B.C
**Classification**: [MAJOR/MINOR/PATCH]

**Impact Assessment**:

- Breaking Changes: [Yes/No]
- New Features: [Yes/No]
- Security Fixes: [Yes/No]

**Recommended Action**: [Update now/Test first/Review carefully]

Quick Classification Chart

Resources

• •Version Range Notation Guide - Detailed caret, tilde, and exact range rules
• •Classification Examples - Real-world version change examples
• •Common Errors Reference - Patterns to avoid

Full Specification

For complete semver rules and standards, see: ~/.claude/standards/semver.md