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:

Bump	Trigger	Examples
Major (X.0.0)	Breaking change	feat!:, fix!:, BREAKING CHANGE: in body/footer
Minor (x.Y.0)	New feature	feat:, feature:
Patch (x.y.Z)	Everything else	fix:, chore:, docs:, style:, refactor:, test:, ci:, perf:

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:

File	Field
pyproject.toml	[project] version = "x.y.z"
package.json	"version": "x.y.z"
Cargo.toml	[package] version = "x.y.z"
VERSION	Plain text file

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

Mistake	Fix
Bumping major for every feat! in pre-1.0	Pre-1.0: breaking changes go in minor
Forgetting to tag after version bump	Always tag: git tag v<version>
Version in multiple files getting out of sync	Use the script to update all detected version files
Non-conventional commit messages	Fall back to keyword analysis, but encourage conventional commits