Revisit versioning policy

[pombredanne]

This is following up from @tdruez comment at aboutcode-org/scancode.io#181 (comment)

Using >= with CalVer is problematic for API changes, see 7b7fc2b
One that would run the install at the moment would encounter issues running the docker pipeline:
'Image' object has no attribute 'base_location'
We should revert back to exact versions.

There is indeed an issue with the lack of semver signaling in the way we use calver so far which is based on yy.m.d and only signals dates and nothing about API compatibility.

We should revisit this here and on all aboutcode.org projects

See https://sbarnea.com/posts/semver-vs-calver/ and https://calver.org/

[pombredanne]

Some semi random thoughts...

See these:

• pip: Switch to CalVer and set a release cadence pypa/pip#5324
• https://bernat.tech/posts/version-numbers/
• https://caremad.io/posts/2016/02/versioning-software/
• https://hynek.me/articles/semver-will-not-save-you/
• https://snarky.ca/why-i-dont-like-semver/

In ssbarnea's post at https://sbarnea.com/posts/semver-vs-calver/ I like this:

Based on what I seen so far, I am going to adopt YY.MINOR.MICRO for all my projects from now on, which happens to be what pip uses.
This means that:

• 20.0 is the first release from 2020 that breaks API compatibility
• 20.2 may also break API and clearly indicates it was not the first release of the year. What the numbers means is left to preferences of the maintainer: you can either increment or just use the month to indicate when it happened. If you make more than 12 breaking-change releases per year you have another kind of issue, which is not the a versioning one.
• 19.0.1 is a release that keeps API compatibility with 2019 versions but it may not necessarily be released in 2019, it could as well be a hot fix release January 2020 for the users of the old version.

This combines the best signaling of semver and calver.

Both calver and semver have issues.... and pepending on the tools we have also varying needs:

• scancode-toolkit has both an evolving API and a data component for licenses that evolves even more quickly. A major API change every year sounds about right, and using backward compatibility flags will help.
• scancode.io would be bound to scancode-toolkit
• other libraries have a lesser time component and mostly API evolution.

I like to think of versions as a way to signal changes/API compatibility AND time obsolescence. And we have projects where we want to signal:

• API compat first and time obsolescence second (most libraries)
• time obsolescence first and API compat first second (most apps and libraries with an evolving data component)

So we may need to use different version conventions for different projects?

Or maybe something such as MAJOR.MINOR.YYYYMMDD... where MAJOR.MINOR are calver/semver-like as proposed in ssbarnea scheme and YYYYMMDD is a calver-like the date of the release? (or just YYMMDD)
PEP

This means that every version signals both on API/Compat AND obsolescence? (This reminds me a bit of the Eclipse versioning scheme that I had helped refine a while back)

Of course we also need to define very clearly what is an API change or not..... which is something super hard as pointed in https://snarky.ca/why-i-dont-like-semver/

[pombredanne]

The latest release is now based on semver.
See https://github.com/nexB/scancode-toolkit/blob/a0d4d814467779e397abdb9d5ebbea2cd25aa40a/docs/source/misc/versioning.rst for docs.