Semantic Versioning vs Calendar Versioning Compared
A version number is a promise about what changed. Semantic versioning promises something about compatibility. Calendar versioning promises something about time. Choose the promise your readers need.
Every release needs a name that can be said aloud, sorted and compared. Two schemes cover most practice: semantic versioning and calendar versioning. They answer different questions, and the choice is a decision about what you want a version number to tell the person reading it.
Semantic versioning
Semantic versioning uses three numbers in the form MAJOR.MINOR.PATCH, for example 2.4.1. The rules, published as the Semantic Versioning specification, are straightforward. Increase the major number when you make an incompatible change to the public interface. Increase the minor number when you add functionality in a way that stays compatible. Increase the patch number when you make compatible bug fixes.
The strength of the scheme is that the number tells a consumer whether upgrading is likely to break them. That is valuable when other people's software depends on yours, which is why it dominates libraries, packages and public APIs. Dependency tools can use the numbers to decide which updates are safe to apply automatically.
The weakness is that it relies on a definition of "public interface" and on honest judgement about what is breaking. In an application used through a screen, with no programmatic consumers, there is no clear line between a compatible and an incompatible change, and teams spend time debating the number.
Calendar versioning
Calendar versioning builds the version from the date, for example 2026.10 for a release in October 2026, or 2026.10.3 for the third release that month. The format is chosen by the project, and several are in use, with the year, month and sometimes day or a counter.
The strength is that the number tells you how old the software is without looking anything up. It suits products that release on a rhythm, applications whose users care about currency more than compatibility, and projects with long-term support periods tied to dates. It removes the argument over what counts as a breaking change.
The weakness is that the number says nothing about compatibility. A consumer cannot tell from 2026.10 whether upgrading from 2026.04 will break them.
How to choose
- If other software depends on yours through a defined interface, prefer semantic versioning.
- If you ship an application on a regular schedule and users are people, calendar versioning is usually simpler and is easy to explain.
- If you ship both an application and a public API, version them separately. The API suits semantic versioning. The application can use dates.
- If you do not number releases at all, name them. A name and a date is better than an inconsistent number.
Rules that apply either way
- Write down the scheme and the rules for choosing the next number, where the whole team can read them.
- Never reuse or change a version after it is published. A number identifies one specific set of changes.
- Make the version visible in the product, in the release notes and in the release record, so that a support request can quote it.
- Treat a hotfix as a release in its own right, with its own number. See the guide to the hotfix release process.
Versions in Atlas
A release in Atlas has an optional version, which can be semantic, such as 2.4.0, or calendar, such as 2026.10, and a type of major, minor, patch or hotfix. The type is a label that describes the release for planning and reporting. It does not change the version automatically, so the two should agree by convention in your team.