CalSemVer

If you want to use dates for versioning (CalVer),
but have to be compatible with SemVer,
CalSemVer is for you!

CalVer is …		SemVer is …
A versioning convention		A versioning specification
That uses a date-based version number		That defines rules for numbers
To represent a project’s code changes.		To describe a project’s code changes.
For instance: 2025.06.07		For instance: 1.2.3

CalSemVer is
a versioning convention
that uses specific CalVer formats
to be Semver compatible.1
For instance: 2025.6.7, 25.6.7 or0.25.6

Motivation

A major issue with any versioning scheme is not whether a newer version is available, but whether a newer version contains backward incompatible changes.

SemVer sought to fix this problem by introducing the concept that a major version number change indicates backward incompatible changes. This solution places the burden of determining compatibility on the developer of the software. As discussed in various places², in practice, it is often not followed correctly (if at all).

CalVer does not try to solve this problem, placing the burden of determining compatibility on the consumer of the software. The main argument for this is that the consumer should be able to determine compatibility, as they should be familiar with the (vendor) code they are using.

CalSemVer is a combination of both approaches, using date-based versions that are SemVer compatible, with the advice to document backward breaking changes (and other changes) in release- or changelogs.³

Any questions not answered in the FAQ can be directed to [email protected]

Shortcomings

The major limitations of CalSemVer are similar to that of SemVer, in that it is up to the developer to make sure they actually follow the rules.

Without strict adherence to the rules, an update in the “major” version (to represent a new year) might not contain any backward incompatible changes.

Conversely, a “minor” version update (to represent a new month) might contain backward incompatible changes.

This limitation, the steps needed to work around it, and whether developers are willing to follow these steps, are explicitly what dictate whether CalSemver is a good fit for a project or whether another versioning scheme should be used instead.⁴

Footnotes