Hacker News Reader

Comment by skrebbel | Hacker News Reader

Any opinions on calver vs semver for, say, open source projects or APIs/SDKs?

For APIs, calver can make a lot of sense, as detailed in Stripe’s blog post on the subject https://stripe.com/en-ca/blog/api-versioning

This is great, thanks for sharing.

That's just because they keep compatibility basically forever (they build middleware to transform older versions to new ones). If you actually want to remove old versions not so much.

Semver is used for regular releases when you need to communicate deeper information to multiple consumers. A library version usually needs to communicate lots of information, to developers, to users, to distributions. Maybe this release is a dev release, while this other is stable, this release is LTS while another is not, this release has breaking changes, this one doesn't, etc.

Calver is used when you don't care about anything but the temporal difference between releases, and you can basically toss any expectation of compatibility between versions, other than something temporal ("this version is compatible with previous versions for up to one year"). That's why APIs use it.

Generally speaking, OSS uses Calver when the releaser doesn't need to care about the consumer, compatibility, etc. You'll find Linux system packages using Calver when someone basically cloned a random Git repo, made a one-off build, and decided "this will be a release" (you find this with firmware a lot), or as a way for 3rd parties to fork an official version with patches.

Random assortment of Ubuntu packages with a variant of Calver (sometimes along with Semver): libargon2, gyp, aspell, language-pack-en, libcrystalhd3, ntfs-3g, x11proto-* , python-cliapp, net-tools, rtmpdump, iputils-*, dh-python, amd64-microcode, lsb-release, libstring-escape-perl, wireless-regdb, ubuntu-keyring, tzdata, fonts-vlgothic, usb-modeswitch-data, publicsuffix, autotools-dev, geoip-database, ca-certificates, dns-root-data

tzdata and several other packages in that list use dated versions because they have very strong expectations of compatibility.

No strong opinion here, but I see calver as a good fit for a new / rapidly changing project (with yyyymmdd being a both version and snapshot date), or for a software where you don't need semver guarantees about api change - so not for a library or for some important tool that is often scripted.

Or, as described in the project, calver might be good as a release date for a "umbrella projects" - like Ubuntu, or even Windows 10 builds.

Semantic versioning tells you a lot about the state of a release. Is it supposed to break backwards compatibility or does it just add new or patch existing backwards compatible functionality? I think that sort of stuff is more important than on what day the release was made.

For an API it seems like a no-brainer to use semantic versioning, makes it easier to document feature deprecation, like supporting latest two major releases and so on.

Something like CalVer forces you to consider every version breaking and puts the responsibility on you to ensure compatibility with your project.

SemVer puts the responsibility on the maintainer to assume how users are using the library.

I think by now we've learned that even though SemVer was a good idea, people are people and they are gonna eventually fail at setting the version correctly, making your assumptions broken

That can be said about any versioning scheme. The idea that making things inconvenient suddenly makes people do the right thing is pretty naive, if you ask me.

Semantic versioning lets the user decide.

Semver still communicates intents pretty well. Well run projects will even roll back changes that ended up being semver incompatible

Treating every patch release of Django like a major release would be a major waste of time compared to “assume Django maintainers have a good idea of how things are used, and rely on automated test suite”

> Semver still communicates intents pretty well. Well run projects will even roll back changes that ended up being semver incompatible

That sounds either worse. Software releases should be immutable, so no changing existing versions.

And also, if X.Y is incompatible (because they screwed up the versioning, as in your example), X.Z should also be incompatible (according to semver), otherwise you break semver twice instead of just once...

> Treating every patch release of Django like a major release would be a major waste of time

Yeah, I guess computing time. If you manually testing each dependency update, your doing something wrong. This should be automated to such level as you feel comfortable stuff is working by just running the tests.

Using a library puts the responsibility on you to ensure compatibility.

With SemVer the library maintainer tells you "here, let me help you". With CalVer the maintainer says "fuck that, I'm out". None changes your responsibility.

At CoreOS (circa 2013+) we used something ideologically similar to CalVer but with tweaked semantics.

As per our documentation (https://coreos.com/releases/): CoreOS Container Linux version numbers are determined by the number of days since the CoreOS epoch, July 1, 2013, at the time the release is built for the Alpha channel.

There were definitely challenges but it provided a rigorous method to ensure monotonically increasing values. It had a useful side effect of getting people out of the habit of "caring" about which version they were running and instead allowed us to focus on simply "being up to date."

AWS seems to use a variation of calendar versioning for some of their APIs. In practice, it seems perfectly fine.

As does Azure

Reply on news.ycombinator.com