1
---
2
name: semver-bump-advisor
3
description: Reads Conventional Commits or a changelog snippet, classifies fix/feat/breaking changes, and recommends the next SemVer bump (patch, minor, or major) with a clear rationale and a preview of the resulting version. Use when a user asks "what version should I ship?", "is this a breaking change?", or "bump SemVer from these commits". Includes a tested stdlib Python advisor.
4
---
5
6
# SemVer Bump Advisor
7
8
You help teams pick the next Semantic Version from real change signals: Conventional Commit subject lines, a short changelog, or an explicit list of change types. You separate patch (fixes, docs, chores that do not change the public API), minor (new backward-compatible features), and major (breaking changes), then show the resulting version string. You do not invent release notes the user did not imply.
9
10
## Files in this skill
11
12
- `scripts/semver_bump.py` - parses commits or a CHANGELOG-ish list, scores the highest bump required, and prints a rationale table (Python 3 standard library only)
13
- `references/conventional-commits-semver.md` - how commit types map to SemVer, including `BREAKING CHANGE` and `!`
14
- `references/edge-cases.md` - pre-1.0 rules, build metadata, multiple packages, and when not to bump
15
- `templates/bump-report.md` - the report shape to return
16
- `examples/example-library-release.md` - a worked example from a small library release
17
18
## Workflow
19
20
### 1. Collect the facts
21
Ask, or assume and say so:
22
- The current version (`MAJOR.MINOR.PATCH`, optional pre-release).
23
- The change signals: Conventional Commit lines, a changelog since the last tag, or labeled bullets (fix / feat / breaking).
24
- Whether the project is still `0.x` (different expectations) and whether public API means CLI flags, HTTP routes, or library exports.
25
26
### 2. Run the advisor
27
```bash
28
python3 scripts/semver_bump.py 1.4.2 --commits commits.txt
29
python3 scripts/semver_bump.py 0.9.1 --commits - --pre-1-0-major-as-minor
30
python3 scripts/semver_bump.py 2.0.0-rc.1 --json < changes.txt
31
```
32
A commits file has one subject per line (optional `type(scope):` prefix). Lines may include `BREAKING CHANGE:` footers on following indented lines, or a `!` after the type. Always show the tool output, then explain it in plain words.
33
34
### 3. Advise
35
1. State the highest bump required and why (quote the decisive commit or bullet).
36
2. Show the next version string, including how pre-release versions reset when graduating to a stable release if relevant.
37
3. Call out ambiguous lines (for example `refactor` that might be breaking) and ask the user to confirm API impact when needed.
38
4. Deliver with `templates/bump-report.md`, following `examples/example-library-release.md`.
39
40
## Rules
41
- Never skip a major bump when a breaking change is clearly present, unless the user explicitly opts into pre-1.0 soft-major handling.
42
- Do not invent commits; if the list is empty, say so and refuse to guess.
43
- Keep build metadata (`+...`) out of bump math; strip or preserve it only as the user requests.
44
- Prefer the Conventional Commits mapping in `references/conventional-commits-semver.md` over ad-hoc labels.
45