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 how to communicate that newer versions contain backward incompatible changes.

CalVer does not try to solve this problem. The main argument for this is that the user should be familiar with the (vendor) code to be able to determine compatibility.

SemVer uses major version number incremenet to indicate backward incompatible changes. The developer of the software defines compatibility. In practice it doesn’t always work right (if at all)².

CalSemVer is a combination of forward going date-based versions with the convention to document backward breaking changes (and other changes) in release- or changelogs³. The version numbers are SemVer compatible and can be parsed by SemVer tools.

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