A new scheme for versioning software projects is gaining popularity: Calendar Versioning. Instead of arbitrary version numbers of SemVer standard, it suggests using release dates. Maybe a good idea for your project?

https://calver.org/

Many of us are familiar with semantic versioning a.k.a. SemVer. In fact, it’s so familiar that we don’t even think about it. When we create a new project, npm automatically inserts 1.0.0 (and we change it to 0.0.1 if we suffer from impostor syndrome).

Then the project continues, releases follow, and the battle begins. Entire meetings are wasted deciding whether particular release is a major or a minor one. As time goes by, these numbers lose their practical meaning. If not for us, then certainly for the end users. Imagine a layperson looking at the About box proudly informing them that they are using version 2.19.1202. They sure are impressed! Wow, such version, much good, look at these bigly numbers 😉

Semantic versioning will likely remain a choice for frameworks and libraries. But it doesn’t feel right in many other scenarios. CalVer kindly suggests a more sensible pattern, based on release dates. After all, time appears to be unidirectional so timestamp should be as good an indicator of progress as any?

Imagine that instead of seeing meaningless numbers like:

2.19.1202
2.19.1243
2.21.103

the user will now see:

2024.1.1
2024.1.12
2024.3.20

For us, the benefit of using calendar-based versions is this:

It tells users when the application was last released. It gives them an immediate idea whether the software they use is outdated. It could prompt them to update.

Setting the version number using CalVer in JavaScript projects is easy. Get the formatted date with date command and use npm version command to set the version of the package. You can define a script in package scripts and use it during the deployment. Unless you care about identifying multiple deployments during the same day, this should be good enough:

  "scripts": {
    "set-version" : "npm version $(date '+%Y.%-m.%-d')"
  }

You can find the details of this proposal here: https://calver.org/