---

name: apply-semantic-versioning locale: caveman-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Apply semantic versioning (SemVer 2.0.0) to determine the correct version bump based on change analysis. Covers major/minor/patch classification, pre-release identifiers, build metadata, and breaking change detection. Use when preparing a new release to determine the correct version number, after merging changes before tagging, evaluating whether a change constitutes a breaking change, adding pre-release identifiers, or resolving disagreement about what version bump is appropriate. license: MIT allowed-tools: Read Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: versioning complexity: intermediate language: multi tags: versioning, semver, version-bump, breaking-changes

Apply Semantic Versioning

Determine + apply correct ver bump via changes since last release. Read ver files, classify changes breaking (major)/feature (minor)/fix (patch), compute new ver, update files. SemVer 2.0.0.

Use When

• Prepare new release → correct ver num
• After merging, before tagging
• Eval change = breaking?
• Add pre-release (alpha, beta, rc)
• Resolve disagreement about ver bump

In

• Required: Project root w/ ver file (DESCRIPTION, package.json, Cargo.toml, pyproject.toml, VERSION)
• Required: Git history since last release (tag or commit)
• Optional: Commit convention (Conventional Commits, free-form)
• Optional: Pre-release label (alpha, beta, rc)
• Optional: Previous ver if not readable

Do

Step 1: Read Current Ver

Locate + read ver file in project root.

# R packages
grep "^Version:" DESCRIPTION

# Node.js
grep '"version"' package.json

# Rust
grep '^version' Cargo.toml

# Python
grep 'version' pyproject.toml

# Plain file
cat VERSION

Parse → major.minor.patch. Pre-release suffix (e.g., 1.2.0-beta.1) → note separately.

→ Current ver = MAJOR.MINOR.PATCH[-PRERELEASE].

If err: No ver file → check VERSION file or git tags (git describe --tags --abbrev=0). No ver → start 0.1.0 initial dev or 1.0.0 if stable public API.

Step 2: Analyze Changes

Changes since last tagged release.

# Find the last version tag
git describe --tags --abbrev=0

# List commits since that tag
git log --oneline v1.2.3..HEAD

# If using Conventional Commits, filter by type
git log --oneline v1.2.3..HEAD | grep -E "^[a-f0-9]+ (feat|fix|BREAKING)"

No tags → compare against initial commit or known baseline.

→ List of commits w/ msgs classifiable by change type.

If err: Git history unavail or tags missing → ask dev describe changes manually. Classify per desc.

Step 3: Classify Changes

Apply SemVer rules:

Change Type	Bump	Examples
Breaking (incompatible API change)	MAJOR	Renamed/removed public fn, changed return type, removed param, changed default behavior
Feature (new backwards-compat)	MINOR	New exported fn, new param w/ default, new file format support
Fix (backwards-compat bug fix)	PATCH	Bug fix, doc correction, perf w/ same API

Rules:

1. ANY breaking → MAJOR (resets minor + patch to 0)
2. No breaking + ANY features → MINOR (resets patch to 0)
3. Only fixes → PATCH

Special:

• Pre-1.0.0: During initial dev (0.x.y), minor bumps may contain breaking changes. Doc clearly.
• Deprecation: Deprecating a fn → MINOR (still works). Removing → MAJOR.
• Internal changes: Refactoring no public API change → PATCH.

→ Each change classified breaking/feature/fix + overall bump level.

If err: Ambiguous → err on side of higher bump. Conservative major > minor breaking downstream.

Step 4: Compute New Ver

Apply bump to current:

Current	Bump	New Version
1.2.3	MAJOR	2.0.0
1.2.3	MINOR	1.3.0
1.2.3	PATCH	1.2.4
0.9.5	MINOR	0.10.0
2.0.0-rc.1	(release)	2.0.0

Pre-release label requested:

• 1.3.0-alpha.1 first alpha of upcoming 1.3.0
• 1.3.0-beta.1 first beta
• 1.3.0-rc.1 first release candidate

Pre-release precedence: alpha < beta < rc < (release).

→ New ver num per SemVer rules.

If err: Current ver malformed or non-SemVer → normalize first. 1.2 → 1.2.0.

Step 5: Update Ver Files

Write new ver to file(s).

# R: Update DESCRIPTION
# Change "Version: 1.2.3" to "Version: 1.3.0"

// Node.js: Update package.json
// Change "version": "1.2.3" to "version": "1.3.0"
// Also update package-lock.json if present

# Rust: Update Cargo.toml
# Change version = "1.2.3" to version = "1.3.0"

Multi files ref ver (_pkgdown.yml, CITATION, codemeta.json) → update all.

→ All ver files updated consistently → new ver.

If err: File update fails → revert all → maintain consistency. Never partially updated state.

Step 6: Create Ver Tag

After committing ver bump, create git tag.

# Annotated tag (preferred)
git tag -a v1.3.0 -m "Release v1.3.0"

# Lightweight tag (acceptable)
git tag v1.3.0

Project's tag format:

• v1.3.0 (most common)
• 1.3.0 (no prefix)
• package-name@1.3.0 (monorepo)

→ Git tag matching new ver.

If err: Tag exists → ver not properly bumped. Check duplicate tags git tag -l "v1.3*" + resolve.

Check

• Current ver read from correct file
• All commits since last release analyzed
• Each change classified breaking/feature/fix
• Bump matches highest-severity (breaking > feature > fix)
• New ver SemVer 2.0.0: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
• All ver files updated consistently
• No ver skipped (1.2.3 → 1.4.0 no 1.3.0 released)
• Git tag matches new ver + project's format
• Pre-release suffix follows correct precedence (alpha < beta < rc)

Traps

• Skip minor versions: 1.2.3 directly → 1.4.0 because "2 features." Each release = 1 bump; num features no determine ver.
• Treat deprecation as breaking: Deprecating (adding warn) = minor. Only removing = breaking.
• Forget pre-1.0.0: Before 1.0.0 API unstable. Some projects bump minor for breaking during this phase, but doc.
• Inconsistent ver files: Update package.json not package-lock.json, or DESCRIPTION not CITATION. All refs sync.
• Build metadata confusion: Build metadata (+build.123) no affect ver precedence. 1.0.0+build.1 + 1.0.0+build.2 same precedence.
• Not tagging releases: No git tags → future ver bumps can't determine baseline for change analysis.

→

• manage-changelog — maintain changelog entries pair w/ ver bumps
• plan-release-cycle — plan release milestones → ver bumps
• release-package-version — R-specific release workflow includes ver bumping
• commit-changes — commit ver bump w/ proper msg
• create-github-release — create GitHub release from ver tag