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

• Parse versions: Extract MAJOR.MINOR.PATCH from both versions

• Strip notation: Remove ^ , ~ , >= prefixes if present

• Compare MAJOR: If different → MAJOR change

• Compare MINOR: If different → MINOR change

• Compare PATCH: If different → PATCH change

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

• Null pointer fix → PATCH candidate

• New method → MINOR upgrade (overrides PATCH)

• 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

• Version must increase: New version > current version

• Only one segment increases: Increment MAJOR OR MINOR OR PATCH

• 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)

• 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/pnpm Commands

View outdated packages with version info

npm outdated

Machine-readable upgrade information

npx ncu --jsonUpgraded

pnpm version check

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

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

Old Version New Version Change Type Classification

1.2.3 2.0.0 X changed MAJOR

1.2.3 1.3.0 Y changed MINOR

1.2.3 1.2.4 Z changed PATCH

^4.0.0 ^5.0.0 X changed MAJOR

~1.2.3 ~1.3.0 Y changed MINOR

9.35.0 9.36.0 Y changed MINOR

0.2.3 0.3.0 Y changed MINOR (0.x)

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