CalVer or SemVer?

Andrea Giammarchi
2 min readJan 31, 2024

This is going to be quick … but after many discussions and a little while behind a project which releases are after CalVer, also side-reflected on npm via SemVer, where this is for us a “canary/dev build”, this is my personal summary:

Why CalVer

  • it signals a project is kept updated and maintained in time
  • it’s semantic for users’ eyes … as in: they instantly understand when their version was released and have an idea of the status of that project (abandoned? outdated version?)
  • … that’s probably it to me …

Why SemVer

  • it doesn’t mentally couple a date on a (hopefully) robust and stable release for software that might be X years or months old and still rock-solid and (maybe) bugs free
  • it clearly separates patches from changes without bounding “meaningful changes” happened in a specific month … actually it frees anyone from thinking “should we release earlier to close this month with the best up to that point and release also ASAP next month to signal these major changes?” … so it removes “unnecessary release friction
  • one can release minor to major within the same month independently, while it would be extremely confusing otherwise to me, understanding why everything breaks between 2024.01.1 and 2024.01.2 (possibly happened the 31st of January … as one month of changes and development might mean everything!)
  • a release before Xmas and a patch after NYE really confuses me … 2023.12.2 and 2024.01.1 might mean everything and nothing at the same time … 1.7.1 on December and 1.7.2 on January would never make me even think about it … it’s a patch: I am good to update!
  • it’s the de-facto industry standard dictated by the biggest community registry that we have right now: npm

As Summary

I start thinking early projects or new ideas might actually benefit more from CalVer approach but in the long run, any serious project should probably move into SemVer because while it’s awesome to realize a project keeps changing in a calendar, it’s also awesome to understand how much it changed, what likely broke, what new feature landed, and what’s been just patched.

That’s it … maybe the least useful post I’ve ever written, but it’s also true I’ve never had a CalVer based experience before (20+ years in development), so it was (imho) somehow worth it writing this down 👋

--

--

Andrea Giammarchi

Web, Mobile, IoT, and all JS things since 00's. Formerly JS engineer at @nokia, @facebook, @twitter.