The three numbers: MAJOR.MINOR.PATCH
A semantic version number has three parts: MAJOR.MINOR.PATCH. Each number has a specific meaning:
- MAJOR — increments when you make breaking changes (changes that require existing users to update their code or config)
- MINOR — increments when you add new features in a backward-compatible way
- PATCH — increments when you fix bugs in a backward-compatible way
When you bump a number, all lower numbers reset to zero. So after 2.4.7: a bug fix becomes 2.4.8, a new feature becomes 2.5.0, a breaking change becomes 3.0.0.
Real examples of when to bump which number
| Change | Version bump | Why |
|---|---|---|
| Fixed a crash on login | PATCH (2.4.7 → 2.4.8) | Bug fix, backward compatible |
| Added dark mode | MINOR (2.4.8 → 2.5.0) | New feature, backward compatible |
| Added dark mode + bug fix | MINOR (2.4.8 → 2.5.0) | MINOR absorbs the patch — only one bump per release |
| Renamed an API endpoint | MAJOR (2.5.0 → 3.0.0) | Breaking change — callers need to update |
| Removed a deprecated feature | MAJOR (3.0.0 → 4.0.0) | Breaking change |
| Changed the config file format | MAJOR | Existing configs break — that's a breaking change |
Pre-release and build metadata
SemVer also supports pre-release identifiers after the version number:
What counts as a "breaking change"?
This is where teams get confused. A breaking change is anything that causes existing, valid usage to stop working:
- Removing or renaming a public API endpoint, function, or class
- Changing the type or format of a parameter
- Changing the format of a config file
- Changing the meaning of a return value
- Removing a feature that users depend on
- Changing default behaviour in a way that affects existing users
Things that are not breaking changes: adding new optional parameters, adding new endpoints, fixing bugs (even if some users depended on the buggy behaviour — that's a judgement call), improving performance, updating documentation.
SemVer and your changelog
Semantic versioning and changelogs work together. The version number signals the severity of change; the changelog explains what specifically changed. A good CHANGELOG.md uses SemVer headers and groups changes by type — matching exactly what the version number communicates.
ChangelogAI generates changelogs that include your version number, date, and properly grouped changes. When you paste your commits, it also infers whether breaking changes are present and flags them in the output.
Common SemVer mistakes
- Treating 0.x.x differently. Before 1.0.0, anything can change at any time — the MINOR version is treated like MAJOR. Be explicit with your users about this.
- Bumping PATCH for new features. "It's just a small feature" isn't PATCH — it's MINOR. Stick to the rules or users can't trust your version numbers.
- Avoiding MAJOR forever. Some teams stay on 1.x.y for years to avoid the psychological weight of "v2." But v2.0.0 signals maturity, not instability.
- Not communicating breaking changes clearly. A MAJOR version bump is not enough — you need release notes that explain what broke and how to migrate.
Connection to release notes: Every MAJOR release should have a migration guide linked from the release notes. ChangelogAI flags breaking changes in the output — use that as your prompt to write the guide.
Frequently Asked Questions
What does v1.0.0 mean?
The first stable public release — where you commit to maintaining backward compatibility. Everything before 1.0.0 (0.x.y) is considered unstable and can change at any time.
Should I use SemVer for a mobile app?
App stores use build numbers and marketing versions differently. You can still use SemVer for the version string (displayed as 3.2.1) even if the internal build number increments separately.
What's the difference between SemVer and CalVer?
SemVer (Semantic Versioning) encodes the type of change in the version number. CalVer (Calendar Versioning) uses the date — e.g. 2026.06.02. Many large projects like Ubuntu and pip use CalVer. Neither is definitively better.
When should I release v1.0.0?
When you're ready to commit to a stable public API and backward compatibility. Staying in 0.x.y too long sends the wrong signal to users. 1.0.0 doesn't mean perfect — it means stable enough to depend on.
Does ChangelogAI support semantic versioning in the output?
Yes. Enter your version number in the version field and ChangelogAI formats it correctly in the output — e.g. ## [2.4.0] — 2026-06-02 for Keep a Changelog format.
Related Tools & Guides
Stop writing release notes by hand
Paste your commits. Get polished, publish-ready release notes in seconds. Completely free, no account needed.
Try ChangelogAI Free →