Semantic Versioning in Changelogs

Conventional Commits Meet Semantic Versioning

Semantic Versioning (SemVer) uses a three-part version number: MAJOR.MINOR.PATCH. Conventional Commits provide a direct mapping from commit types to version increments.

The Mapping Rules

Condition	Version Bump	Example
Any commit with ! or BREAKING CHANGE	MAJOR	1.2.3 → 2.0.0
Any feat commit (no breaking)	MINOR	1.2.3 → 1.3.0
Only fix, docs, chore, etc. (no feat, no breaking)	PATCH	1.2.3 → 1.2.4

Determining the Version

Before entering the version in the generator, scan your commits:

1. Are there any breaking changes? → Increment MAJOR, reset MINOR and PATCH to 0.
2. Are there any feat commits? → Increment MINOR, reset PATCH to 0.
3. Otherwise → Increment PATCH.

Example Commit Set

feat(auth): add OAuth2 login
fix(ui): correct sidebar z-index
docs: update README

This set contains a feat but no breaking changes, so the version should be a MINOR bump. If the previous release was 1.2.3, the new version would be 1.3.0.

Pre-release Versions

SemVer supports pre-release identifiers like 2.0.0-beta.1 or 1.3.0-rc.1. The generator accepts any version string, so you can enter pre-release versions directly in the version input field.

The Changelog as a Contract

When your changelog is versioned with SemVer, it becomes a contract with your users. The version number tells them the risk level of upgrading (patch = safe, minor = new features but backward-compatible, major = breaking changes), and the changelog details explain exactly what changed.