CalVer is many schemes

A project I work on is preparing to pilot our initial version. As part of that preparation, we needed to decide on a versioning scheme. Someone proposed using calendar versioning and we all agreed. “Okay,” I asked, “what does that actually mean?” Unlike Semantic Versioning (SemVer)’s defined standard, Calendar Versioning (CalVer) is an umbrella of many possible date-related schemes.

What is Calendar Versioning?

Calendar Versioning is release numbering based on a calendar date of some kind. Most CalVer schemes involve the year in either two- or four-digit form. Sometimes, the next part is more date. For example, Ubuntu releases are numbered based on the two-digit year and two-digit month. Other times, the next part is a incremented identifier. The tzdata time zone database uses the year plus a lowercase letter.

Choosing a CalVer scheme

The first question is, of course, if you should use CalVer at all. CalVer works well when time is more important than communicating compatibility. This might be because compatibility isn’t a relevant concept, like with data or standards, or because compatibility is hard to define, like a Linux distribution.

The next question to ask is “how predictable are releases?” If you expect to have a few well-spaced releases a year, using the month number is a good choice. If you expect to have more than one per month regularly, then adding the month and day is a good approach. If releases could happen at any moment, an incremented system is a better approach. Time zone boundaries and daylight saving time observances can change whenever one of hundreds of nations decide to make a change, so it makes sense for the tzdata project to not go with a higher resolution date than the year.

No matter what CalVer variant you choose, you need to clearly indicate how you identify your releases. Simply saying “CalVer” does not set clear expectations for your users.

This post’s featured photo by Towfiqu barbhuiya on Unsplash.