CalVer vs. SemVer

[fhightower]

I would like to consider (and articulate why) democritus project will use one versioning system over the other.

[fhightower]

A few thoughts:

It seems:

• that CalVer (to be done well) requires some articulation of project processes and timelines outside of the versioning system
• that CalVer is better for comparing one version to time (e.g. If I have version 2015-01-01 installed, it is very easy to know how old this version is)
• SemVer is better for comparing one version to another (e.g. If I am upgrading from version 0.0.1 to 1.0.0, I know that there are breaking changes involved)

[fhightower]

TL;DR

⚠️ UPDATE - MARCH 2021: This is an old comment and the details no longer apply; see subsequent comments for more details. ⚠️

The democritus project will use a variation of calver that includes a major version to communicate breaking changes. It will take the form: MAJOR.YYYY.0M.0D. If there are multiple releases on the same day, the form will be: MAJOR.YYYY.0M.0D.MINOR.

General Thoughts

I believe the goal of versioning software is so that humans and machines can differentiate versions of software. Thus, a versioning system's effectiveness should be measured by its ability to communicate what is different between versions of software.

Thoughts on SemVer

• Very helpful communication of breaking changes
• It is not always clear what constitutes a breaking change
• Incrementation of minor/patch versions are less informative when comparing versions

Thoughts on CalVer

• Very helpful in communicating time diff between two packages
• Helpful for certain types of projects (e.g. those that are tied to temporal changes (e.g. pytz) or those that are designed to be kept up to date (like a utility library))
• Notes some valid limitations with SemVer, but seems to throw the baby out with the bath water in that it appeals largely to edge-cases and mis-uses of SemVer to discount it

Versioning in Democritus

After some consideration, packages in the Democritus project will be versioned like:

MAJOR.YYYY.0M.0D

(using the terminology described here)

If there are multiple releases on one day, the version will be:

MAJOR.YYYY.0M.0D.MINOR

A bump of the major version communicates that the authors intend a breaking change (e.g. there is a breaking change between 1.2021.01.13 and 2.2021.01.14)

Versions starting with 0. shall be considered in development (as in SemVer) and may change at any time without incrementing the MAJOR version.

Sources

Inspirations for our versioning scheme:

• https://avatao.com/semancat-versioning/
• https://github.com/mahmoud/calver/issues/5 (the first comment suggests this system and provides links to a system using it)

Validation

I have validated this scheme using the packaging library:

from packaging.version import parse

version = '1.2020.01.13'
parse(version)

[fhightower]

⚠️ UPDATE ⚠️

The versioning scheme described in the previous comment has changed and the Democritus Project will use Semantic Versioning.

Why SemVer?

Short Answer

There are four reasons:

1. No/few good reasons not to use it
2. SemVer meaningfully and effectively communicates what is important (the intended scope of a change)
3. SemVer is established and widely used/understood
4. It is easy to move from SemVer to another versioning scheme (like MAJOR.YYYY.0M.0D which was originally chosen for this project)

Long Answer

There is a recent movement against Semantic Versioning (semver) and I sympathize with some of the points raised against semver. That being said, most of the objections to semver I have read are not really objections to semver, but objections to:

• Misuses and abuses of semver (e.g. https://0ver.org/)
• Overly idealistic expectations about semver (e.g. It is silly to assume (without validation) that a minor or patch change will never break anyone's software - ever)

Hence, I am aware of very few, substantive reasons why I would use something other than semver. Additionally, I think Semantic Versioning is effective as it provides a meaningful and reasonable way to communicate changes (or at least intentions) across versions. Many calendar versioning schemes give up on the endeavour of communicating intentions entirely which is, I believe, unwise. If I am comparing version 2018.01.01 with 2018.02.01, I know nothing other than the fact that those two versions are one month apart. Using SemVer (even with some legitimate ambiguities around what constitutes a breaking vs. non-breaking change), at least gives me the chance to estimate the scope of the change. Thus, I believe the, albeit imperfect, communication of intentions is more valuable than giving up on the endeavour entirely.

In addition, there are two other reasons we are using semver. First, it is a well established and understood standard that is widely used (and it is a good practice to use standards, when possible and reasonable). Second, it is easy to switch from semantic versioning to a different versioning scheme, like the one detailed in previous comments, if semver is not working.

Future Changes?

If we do change at any point in the future, we will likely be changing to the CalVer scheme: MAJOR.YYYY.0M.0D or FerVer (like semantic versioning, but allows "minor" breaking changes to be shipped with a minor version bump).