Blog

Semantic versioning and your changelog: which number to bump

Semantic Versioning ties the number of a release to the kind of change in it: a breaking change raises the major number, a new feature that does not break anything raises the minor number, and a bug fix raises the patch number. Your changelog is where you explain the change, and the version number is where you signal how risky it is to upgrade.

This guide shows how the two fit together: what to bump, how the change types of a Keep a Changelog file map to a version number, and what to do when you do not follow Semantic Versioning.

The three numbers

A Semantic Versioning number has three parts, written MAJOR.MINOR.PATCH, as defined in the Semantic Versioning 2.0.0 specification:

  • MAJOR changes when you make an incompatible change to the public API, so existing users may need to change their code.
  • MINOR changes when you add functionality in a backward compatible way.
  • PATCH changes when you make backward compatible bug fixes.
MAJOR2.0.0IncompatibleAPI changeRemoved, or a breaking ChangedMINOR1.3.0New feature,backward compatibleAddedPATCH1.2.1Bug fix,backward compatibleFixed
How the kind of change maps to the version number (Semantic Versioning 2.0.0).

How changelog headings map to a version bump

The Keep a Changelog format groups entries under six headings. They suggest which number to bump, although the decision always depends on whether the change breaks existing users:

HeadingUsually means
AddedA new feature that breaks nothing: a minor release.
FixedA bug fix that breaks nothing: a patch release.
ChangedDepends. A backward compatible change is minor or patch. A breaking change is major.
DeprecatedSomething will be removed later. The specification requires at least a minor release when public API functionality is deprecated.
RemovedSomething users could rely on is gone: normally a major release.
SecurityA vulnerability fix. If it breaks nothing it is a patch, and the entry should say which versions were affected.

Breaking changes belong at the top

When a release has a breaking change, put it first in the entry and say what the reader has to do. For example: "Breaking: createClient() now requires an apiKey option. Pass the key you used to read from the environment." The major number warns people that something needs attention, and the entry tells them what.

Versions before 1.0.0 and pre-releases

  • 0.y.z is for initial development. The specification says anything may change at any time, so readers should not assume a stable API. Many projects use 0.x until they are ready to promise stability with 1.0.0.
  • Pre-release tags such as 2.0.0-beta.1 mark a version that is not yet stable. List them in the changelog when people can install them, and fold the entries into the final release when it ships.

When Semantic Versioning does not fit

Semantic Versioning is written for software with a public API. A web application that users never install has no API to break, so many teams use calendar versions such as 2026.11.19 or a plain date instead. That is fine, and a changelog works either way: keep the version or date in the heading, newest first, in ISO form. The Keep a Changelog format does not require Semantic Versioning, though it asks you to mention whether you follow Semantic Versioning.

Check your changelog

If you want to see whether a file follows the format, paste it into the free CHANGELOG.md validator. It runs in your browser and flags missing dates, wrong headings and versions in the wrong order. For the writing itself, see the guide on how to write a changelog.

ReleaseTale sorts the commits of a release into Added, Changed and Fixed, and lists breaking changes separately in the developer entry. You review it before you save. See the changelog examples for a sample.

Frequently asked questions

How does Semantic Versioning relate to a changelog?

The version number signals how risky an upgrade is, and the changelog explains the change. A breaking change raises the major number, a backward compatible feature raises the minor number, and a bug fix raises the patch number.

Does Keep a Changelog require Semantic Versioning?

No. Keep a Changelog is a format for the file, and it does not require a numbering scheme. Its own template asks you to mention whether you follow Semantic Versioning, so say whether you do.

What should I do for a breaking change?

Raise the major number, put the change first in the entry marked as breaking, and say what readers must change in their code or settings.

Related articles