Semantic Versioning

Determine the next version from commit history when preparing a release. The highest-impact release-relevant commit drives the bump.

When to Activate

• Before or after pushing changes (suggest the version bump)
• When the user asks "what version should this be?"
• When preparing a release or tag
• When reviewing a set of commits for release notes

Version Rules

Follows Semantic Versioning 2.0.0:

The highest bump wins: if any commit is major, the release is major — regardless of how many patches are in the batch.

How to Check

Run the analysis script:

uv run skills/semantic-versioning/scripts/version-bump.py [repo-path]

Options:

• --apply — update the version file after confirmation
• --tag — also create a git tag

Version File Detection

The script auto-detects where the version lives:

Workflow

1. Analyze — scan commits since last tag, classify each
2. Report — show the bump type, commit breakdown, and suggested next version
3. Confirm — wait for user approval before making changes
4. Apply (if --apply) — update version file and optionally tag

Never auto-apply version changes without user confirmation.

Commit Format Guide

For best results, follow conventional commits:

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

If commits don't follow conventional format, fall back to keyword analysis:

• Words like "add", "new", "feature" → minor
• Words like "fix", "bug", "patch", "correct" → patch
• Words like "breaking", "remove", "drop", "rename API" → major

Pre-1.0 Semantics

For versions 0.y.z (pre-stable):

• API is considered unstable
• Minor bumps may include breaking changes
• Use 0.y.z until the project declares stability

Common Mistakes