Skip to content

skillGit and releases

Semantic Versioning

Works out the next version number from the real changes since the last tag, applies semver rules to breaking changes and drafts the release notes.

npx workspacetemplates add semantic-versioning --tool claude-code

Writes 1 file to .claude/skills/semantic-versioning/

.claude/skills/semantic-versioning/SKILL.md29 lines · 1.9 KBFile
---
name: semantic-versioning
description: Works out the next version number from the real changes since the last tag, applies semver rules to breaking changes and drafts the release notes.
---

# Semantic versioning

Decide the bump from what consumers can observe, not from commit prefixes.

## Steps

1. Find the last release: `git describe --tags --abbrev=0` and its tag. If versions below 1.0.0, say so: 0.x allows breaking changes in minor releases, but still note them.
2. Read the change since then: `git diff <tag>..HEAD --stat` and the diff of every file that is part of the public surface (exports, CLI flags, config keys, HTTP routes, database or file formats, environment variables).
3. Classify each change:
   - **Major**: removed or renamed public item, changed argument order or type, narrower accepted input, different return shape, changed default that alters results, dropped runtime or platform support, new required config.
   - **Minor**: new optional feature, new export, wider accepted input, new optional field, deprecation (with the old path still working).
   - **Patch**: bug fix that restores documented behavior, performance work, internal refactor, docs.
4. The highest class wins. A fix that changes behavior people relied on is a major, even if it was a bug.
5. Check internal consistency: update the version in every place it lives (`package.json`, lockfile, `pyproject.toml`, `Cargo.toml`, a version constant), the changelog, and any migration note a major bump needs.
6. Pre-releases use `-rc.1` style suffixes; build metadata uses `+` and never affects ordering.

## Rules

- Do not create the tag or publish. Propose the version and the file edits.
- If a change is ambiguous, list it under "judgment calls" and choose the higher bump.

## Report

The version, the list of changes grouped by class with the file for each, the judgment calls, and draft release notes written for users.

What it does

Version numbers are a promise to the people who depend on you. Picking one from the commit titles alone misses a changed default, a removed export or a stricter validation, each of which breaks someone.

This skill reads the actual public surface that changed, classifies every change as major, minor or patch, and explains the pick so the number can be defended in review.

Example

you › We last released 2.3.1. What should the next version be?

agent › Recommend 3.0.0. Breaking: `parse()` now throws on empty input (returned null in 2.x) and `--legacy-dates` was removed. Minor: new `parseAll()` export. Patch: three fixes. Judgment call: the stricter timezone check is a major because 2.x accepted those inputs. Draft notes and a migration paragraph attached.

Questions

Does it need conventional commits?
No. It works from the diff of the public surface, and commit prefixes are only used as a hint.
Why is a bug fix sometimes a major bump?
If users depend on the old output, correcting it breaks them. Semver counts what callers see, whatever the cause.
  • Git Bisect Regression

    SkillGit and releases

    Free
  • Git Conflict Resolution

    SkillGit and releases

    Free
  • Git History Cleanup

    SkillGit and releases

    Free
  • Monorepo Management

    Skilltypescript

    Free