semver-advisor_skill

Overview

This skill advises on semantic version bumps and classifies version changes according to semver rules. It helps decide MAJOR, MINOR, or PATCH updates, validate proposed versions, and analyze dependency changes for appropriate release decisions. Use it to standardize versioning and avoid common semver mistakes.

How this skill works

It parses MAJOR.MINOR.PATCH from inputs, strips range prefixes (e.g., ^, ~, >=), and compares segments to classify changes. For release planning it evaluates a list of changes, escalates the bump level based on the most severe item (breaking → MAJOR, feature → MINOR, bug → PATCH), and validates proposed versions against increment and reset rules. It also recognizes pre-release labels and enforces precedence and reset semantics.

When to use it

• When proposing a new release and you need a recommended bump level
• When reviewing dependency version changes to classify impact
• When validating that a proposed version follows semver increment/reset rules
• When auditing changelogs to determine required research depth
• When handling pre-release tags or comparing prerelease precedence

Best practices

• Always strip range notation before comparing numeric segments (ignore ^, ~, >=)
• Start with PATCH and escalate to the highest severity found in the change list
• When incrementing MAJOR or MINOR, reset lower segments to 0 (e.g., 1.5.3 → 2.0.0 or 1.6.0)
• Match the bump to the most severe change: breaking → MAJOR, feature → MINOR, fixes only → PATCH
• Document migration notes for MAJOR bumps and run compatibility tests for MINOR changes

Example use cases

• Classify package upgrade 1.2.3 → 1.3.0 as MINOR because MINOR changed
• Recommend MINOR when release includes new public API but no breaking changes
• Validate that proposed 1.5.3 → 2.1.0 is invalid for a MAJOR bump because lower segments were not reset
• Decide PATCH for a release that only contains bug fixes and documentation updates
• Assess dependency updates from ^4.0.0 → ^5.0.0 as MAJOR after stripping caret and comparing MAJOR numbers