Skip to content
Skills Library
Programming · Planning

versioning

/versioning

Use when deciding a version number: bumping a version, cutting a release, tagging, writing a changelog entry, setting up versioning for a project, or when asked which versioning scheme to use (SemVer, CalVer, build numbers). Detects the project's scheme and picks the next version correctly.

Repository
habits ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when deciding a version number: bumping a version, cutting a release, tagging, writing a changelog entry, setting up versioning for a project, or when asked which versioning scheme to use (SemVer, CalVer, build numbers). Detects the project's scheme and picks the next version correctly.

Original author description

Use when deciding a version number: bumping a version, cutting a release, tagging, writing a changelog entry, setting up versioning for a project, or when asked which versioning scheme to use (SemVer, CalVer, build numbers). Detects the project's scheme and picks the next version correctly.

How it works

  1. 1. Detect the scheme in use
  2. 2. The schemes, and when each fits
  3. 3. Picking the next SemVer version
  4. 4. Rules
Original SKILL.md headings · 44 lines, 461 words
SKILL.md preview
---
name: versioning
description: >
  Use when deciding a version number: bumping a version, cutting a release, tagging, writing a changelog entry,
  setting up versioning for a project, or when asked which versioning scheme to use (SemVer, CalVer, build numbers).
  Detects the project's scheme and picks the next version correctly.
---

# Versioning

## 1. Detect the scheme in use

Follow what the project already does; never switch schemes as a side effect.

- Tags: `git tag --sort=-creatordate | head`. Note the format (`v1.2.3`, `1.2.3`, `2026.11.0`, `app-v1.2.3` per package).
- Version sources: `package.json`, `gradle.properties` / `build.gradle(.kts)`, `pom.xml`, `Cargo.toml`, `pyproject.toml`, `.claude-plugin/plugin.json`, Xcode `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION`, Android `versionName` / `versionCode`.
- Release tooling owns the number when present: release-please, semantic-release, changesets. Then you don't edit versions by hand; you write the commits or changesets that drive them.
- `CHANGELOG.md`: keep its existing format (Keep a Changelog or the tool's generated style).

## 2. The schemes, and when each fits

| Scheme | Shape | Fits |
|---|---|---|
| SemVer | `MAJOR.MINOR.PATCH` | libraries, CLIs, plugins, APIs: anything others depend on |
| CalVer | `YYYY.MM.MICRO` or `YY.MM` | apps and services released on a schedule, where "how new" matters more than compatibility |
| Build numbers | an always-increasing integer | store builds: Android `versionCode`, iOS `CURRENT_PROJECT_VERSION`, next to a user-facing SemVer or CalVer |
| Unversioned | commit SHA | continuously deployed sites and services with no consumers of a version |

When setting up a new project, recommend SemVer for anything with consumers and CalVer for scheduled apps, and say why.

## 3. Picking the next SemVer version

From the Conventional Commits since the last tag (`git log <last-tag>..HEAD --oneline`):
- any `!` or `BREAKING CHANGE` footer: MAJOR (before 1.0.0, bump MINOR instead)
- any `feat`: MINOR
- otherwise any `fix` or `perf`: PATCH
- only `docs`, `chore`, `ci`, `test`, `style`, `refactor`: no release needed

Breaking means a consumer has to change something: removed or renamed public API, changed behaviour they rely on, raised minimum runtime or platform. Internal refactors are never breaking.

Pre-releases: `1.3.0-rc.1`, `1.3.0-beta.2`, ordered and incremented within their label; the final release drops the suffix. `0.x` signals an unstable API; move to `1.0.0` when the API is something you commit to.

## 4. Rules

- One version, one meaning: never re-tag or move a published tag, and never reuse a version number. A broken release gets a new patch.
- Bump every place that holds the version in the same commit (manifest, lockfile entries, plugin.json, app version files), conventionally `chore(release): x.y.z`.
- Mobile: increase the build number for every store upload, even when the user-facing version stays the same.
- Monorepos: either one version for everything (fixed) or per-package versions (independent, with per-package tags like `pkg@1.2.3`). Follow the project's choice; changesets and release-please both support either.
- Tag after the release commit is on the release branch, and push tags explicitly (`git push origin <tag>`) only with the user's go-ahead.
- Changelog entries describe what changed for users, grouped by Added / Changed / Fixed / Removed, newest first.

Versions

The database has no other skills named versioning.

Database snapshot: 13.11.2026 · package version df01c1976f9f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100release-versioning-and-changelog-automation
    Establishes a version numbering scheme (SemVer or CalVer) and automates changelog generation and release tagging from commit history, typically via Conventional Commits and tools like semantic-release or release-please. Use when the user asks to "set up semantic versioning,"…
  • 100release
    Versioning and CHANGELOG: SemVer mapped from Conventional Commits, Keep a Changelog format, tagging, pre-release gates. Use when cutting a version: bumping, writing the CHANGELOG entry, or tagging.
  • 100versioning-releases
    This skill should be used when the user is choosing a versioning scheme, writing a changelog, preparing a release, configuring Towncrier or python-semantic-release, planning deprecations, managing major version migrations, or setting up version single-source-of-truth. Covers…
  • 90rseng-publishing-releasing
    Covers the release lifecycle of research software: preparing and cutting versioned releases with changelogs, versioning schemes, release automation and minting a DOI per release. Use when the user asks how to tag a v1.0.0 release, write release notes or a changelog, pick a…
  • 90oss-release-policy
    Writes an open-source project's release policy as a RELEASES.md contract: the versioning scheme (SemVer, 0.x, CalVer such as YY.N, Go /vN majors, PEP 440, epochs, build numbers), what counts as breaking, pre-release channels, cadence, supported versions and LTS windows,…
  • 100calver
    Show or bump the project's CalVer version. Use when user says "calver", "bump version", "what version", or wants to check or set the skills version. For the full release flow (commit + push + PR) use /release-alpha or /release-stable instead — /calver alone never commits, pushes, or PRs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.