Versioning Schema

[waynew]

This is a discussion around our versioning schema for this module. There are two top level choices: cavler or semver.

I'll drop the arguments for/against that seem most valid to me - if I miss any points that you feel are relevant, add them to the discussion!

Semver

Assuming MAJOR.MINOR.PATCH versions.

Semantic versioning is good for library code, which this is - many organizations have upgrade policies where they will not upgrade the MAJOR version except during specific cycles (sometimes annually). Depending on our release cadence, if we're releasing multiple times per month, being able to bump the minor or patch versions and leave the major version alone could be desirable.

The other thing that semver allows is a simple machine readable way of identifying breaking changes. This does require a public API - technically speaking that should be whatever Salt entrypoints (states/modules/beacons/etc) that we expose, which should be documented already.

The only real potential downside is that we might inadvertently break behavior without breaking the API, so users might upgrade and get different behavior.

Calver

There are a few different schemes we could use:

YYYY.MM.DD.PATCH
YYYY.MM.PATCH
YYMM.PATCH
YY.MM.PATCH
YYMM.DD.PATCH

Or... more. My proposal would be YYYY.MM.PATCH - I don't have any problem with 4-segment specifiers, but some places cry with more than 3 segments. YY.MM.PATCH would also be acceptable.

Calendar based versioning is nice because you never wonder when a version was released. It's right there in the version number. Salt used to use calver, but doesn't any longer. That mismatch might be confusing - both for contributors and consumers. Or maybe nobody would notice.

We should be keeping a changelog regardless, so consumers should get in the habit of checking the changelog for breaking changes or unexpected shifts in behavior.

The only potential downside here is that if we're making multiple releases per day (either bugfixes, or if we go pure CD) that we need a PATCH version and can't just go with YYYY.MM.DD. And we lose any major/minor/patch semantics that we could inject into the versions.

[wb529kq]

Semver

[waynew]

Not clear in this discussion, but we settled on using calver: YY.MM.DD(.PATCH), since we'll be releasing ~2wks.