FAQ

How can I use CalSemVer, but be SemVer compliant?

CalSemver (just like CalVer) does not support the concept of a “major” number to represent backward incompatible changes.

It can be made compliant by only breaking backward compatibility once a year, every year.

An alternative is to prefix the version with a 0 so you’re allowed to whatever you want, as per spec. (e.g. 0.24.3)

If you don’t publish a release every month, it is perfectly fine to “skip” versions.1

Item 7 of the SemVer spec states:

“Patch version MUST be reset to 0 when minor version is incremented.”

If you don’t want to skip “zero” versions, a good yearly “zero” is updating any mentions of the year in the codebase, like copyright notices or “is maintained” badges.2

I don’t like using full years!

That’s not a question, but that’s okay.

You can use short years (e.g. 24 instead of 2024) as long as they aren’t zero-padded, as that would break SemVer compatibility.

Is this some kind of (april fools) joke?

All jokes aside, despite trying to keep things light-hearted, this is a serious attempt to solve a real problem.

Isn’t this just another case of XKCD#927?

From one perspective, CalSemVer is not trying to compete with either CalVer or Semver, but from another perspective that can seem to be the case.

The nuance here is that CalSemVer isn’t aiming to replace either versioning scheme but supplement them.

In regard to CalVer, it simply specifies format. Nothing more.

In regard to SemVer, it specifies rules on how to most closely adhere to the spec, while still using a date-based version number.

What if I don’t agree?

Use something else. Seriously, life is too short and there are plenty of perfectly acceptable alternatives out there:

  • CalVer - Versioning using dates.
  • EffVer - Versioning that how much effort it will cost to adopt a new version.
  • HashVer - Versioning using hashes, for instance Git commit hashes.
  • KelVer - Versioning using ever decreasing natural numbers (i.e. negative integers)
  • NameVer - Versioning using names instead of numbers, for instance “Bionic Beaver”.
  • NatVer (or IntVer) - Versioning using ever-increasing natural numbers (i.e. positive integers), for instance SVN revision numbers.
  • PrideVer - Versioning based on how proud (or ashamed) a developer is of their release.
  • RandVer - Versioning using random numbers, for instance UUIDs.
  • SemVer - Versioning using a set of three numbers to denote backwards incompatible, backwards compatible, and bugfix changes.

Just make sure to document your choice, so others can understand your reasoning.3

What is CalSemVer a good match for?

The original (and probably most useful) usecase, is for a tool or service that combines several subsystems or tools, that all have their own version. In such cases, SemVer is not sufficient to represent the changes in the underlying code.

This was the case for the Pipeline Components project, where the idea for CalSemVer originated.

What is CalSemVer not a good match for?

If you create a library or package that is used by other developers, or if you work in a more strict (or more corporate) setting, CalSemVer might not be the best choice. For one thing, it will create confusion among developers who are used to SemVer. Another issue is that your versioning scheme will not be compatible with other teams or packages within your organization.

Unless you can convince your colleagues to use CalSemVer as well, you’re probably better off using SemVer.

A final, more negative, scenario is if your developers habitually ignore their problems, and instead prefer to use magic more code, both the simplicity of CalSemVer and the responsibility it places on developers will not be popular.

In such cases, you’re probably better off following the herds down to greece in picking SemVer.4

What’s in a version number anyway?

Whenever possible, use simple dates instead of version numbers. And if you absolutely, positively *must* use version numbers internally, make them dates anyway. ~ Jeff Atwood5

Source: https://blog.codinghorror.com/whats-in-a-version-number-anyway/

Footnotes

  1. This question has been asked and answered multiple times: https://github.com/semver/semver/issues/942, https://github.com/semver/semver/issues/233, and https://github.com/semver/semver/pull/393 ↩

  2. For instance https://shields.io/badges/maintenance: "is maintained" badge ↩

  3. Yes, I know. Documentation, like eurgh, right? ↩

  4. And then ignoring the spec it provides 😞 ↩

  5. Co-founder of Stack Overflow and Discourse ↩