What semantic versioning actually promises
Semantic Versioning (SemVer) is a contract between a package's maintainer and everyone depending on it. A version number in the format MAJOR.MINOR.PATCH is supposed to tell a consumer, without reading a single line of the changelog, whether it's safe to upgrade automatically. That promise only holds if the bump rules are applied consistently.
The three rules
MAJOR increments when you make an incompatible, breaking API change — something that could break code depending on the previous behavior. When MAJOR increments, MINOR and PATCH both reset to zero. Example: 1.5.2 with a breaking change becomes 2.0.0, not 2.5.2.
MINOR increments when you add functionality in a backwards-compatible way — new features that don't break existing usage. When MINOR increments, PATCH resets to zero. Example: 1.2.3 with a new feature becomes 1.3.0, not 1.3.3.
PATCH increments for backwards-compatible bug fixes only — no new functionality, no breaking changes. Example: 1.2.3 with a bug fix becomes 1.2.4.
What happens when a release has more than one kind of change
This is where teams most often get it wrong under time pressure. If a release includes both a new feature and a bug fix, the correct bump is MINOR (the higher-priority change wins) — you do not bump PATCH for the fix and then separately bump MINOR for the feature. The priority order is always: breaking change beats new feature beats bug fix. Whichever is the highest-priority change present determines the single bump for the release, and the lower segments reset accordingly.
Pairing the version bump with a changelog entry
A version number alone doesn't tell anyone what changed. The Keep a Changelog convention (keepachangelog.com) standardizes this with dated entries and consistent section headers — ### Added for new features, ### Changed for changes to existing behavior (including breaking changes, clearly marked), and ### Fixed for bug fixes. Generating this structure automatically from the same checkboxes you used to compute the version bump keeps the two in sync and removes a step people often skip when rushing a release.
A quick pre-release checklist
- Identify every user-facing change since the last release and classify each as breaking, feature, or fix.
- Apply the highest-priority bump — never stack bumps for multiple change types.
- Reset lower segments to zero according to the rule that applies.
- Write a changelog entry the moment you tag the release, not days later from memory.
Getting this right consistently, release after release, is what makes SemVer useful to the people depending on your package — and it takes seconds to check once you're not doing the arithmetic by hand.
Frequently Asked Questions
1.3.0. Per SemVer rules, a MINOR bump resets the PATCH segment to zero — the tool applies this automatically so you never have to do the arithmetic by hand.
Yes — SemVer & Changelog Calculator applies correct SemVer bump-and-reset rules to your current version and generates a matching changelog stub. It's a one-time $4.49 purchase — no subscription, no account required.
The highest-priority change wins — a breaking change always triggers a MAJOR bump even if the release also includes minor fixes. The tool applies breaking > feature > fix priority automatically when multiple boxes are checked.
It generates a correctly structured Keep a Changelog-style stub with dated headers and placeholder bullets under Added/Changed/Fixed based on what you selected — you then fill in the actual details of what changed before publishing.
The calculator focuses on standard MAJOR.MINOR.PATCH bumping for the core three-part version. Pre-release and build-metadata suffixes are outside its current scope.