CalVer is a software versioning convention that is based on your project's release calendar, instead of arbitrary numbers.
Software versioning gets better with time.
For engineers, versioning allows us to specify precise dependencies within ever-expanding software ecosystems. For marketers, the version is the dynamic part of a project's brand. For all of us, software versioning lets us reference the past while upgrading to the future.
Different software projects use different systems for versioning, but some common practices have emerged. Numeric, decimal point separation, e.g., 3.1.4, is all but given. Another common versioning pattern incorporates a time-based element, usually part of the release date, into the version.
This date-based approach has come to be called Calendar Versioning, or CalVer for short.
There are multiple calendar versioning schemes, long used by projects big and small. Rather than declaring a single scheme to be CalVer, it's important to recognize the practicality of each and design the scheme to fit the project. First, the parts of the version:
The vast majority of modern software versions are composed of two or three numeric segments, plus the optional modifier. Convention suggests that four-numeric-segment versions are discouraged.
As seen in the case studies below, projects have found more than one useful way to leverage dates in their versions. Rather than choose a single scheme, CalVer introduces standard terminology for developers, based on current practices and conventions.
YYYY
- Full year - 2006, 2016YY
- Short year - 6, 16, 106MM
- Short month - 1, 2 ... 11, 120M
- Zero-padded month - 01, 02 ... 11, 12DD
- Short day - 1, 2 ... 30, 310D
- Zero-padded day - 01, 02 ... 30, 31Note that traditional, incremented version numbers are 0-based, whereas date segments are 1-based.
The Gregorian calendar is assumed, as is the convention of UTC. Technically any calendar can be used, provided projects state which one.
CalVer has quite a few users. These are projects selected for their notability and variety of use cases.
Ubuntu, one of the most prominent Linux-based operating systems available, uses a three-segment CalVer scheme, with a short year and zero-padded month. It has done so from the very start, in October 2004, making 4.10 the first general release of Ubuntu.
Even a simple operating system involves many, many parts, making it difficult to communicate much meaning with an arbitrary number. By dating the software release, the calendar-based version is much more than an arbitrary number, communicating useful information that is rooted in simple fact.
Ubuntu derives additional benefit from its CalVer scheme, by integrating it with their support schedule. Ubuntu currently has five-year support periods for their long-term support (LTS) releases, and only 9 months for non-LTS releases. Thanks to CalVer and elementary arithmetic, any user can easily determine whether their version is still supported. The current LTS release at the time of writing, 16.04, will be supported until April 2021.
Twisted, the venerated Python networking and asynchronous execution framework, uses a three-segment CalVer scheme, with a short year in the major version slot.
First released in 2002 and still actively developed today, Twisted is a mature library that has grown to match its large scope. It features everything from an IRC client to an HTTP server to a slew of utilities for concurrent programming. Like an operating system, there are a lot of parts, and what triggers a micro-segment update versus a minor-segment update is completely up to maintainers.
The CalVer major segment provides a definitive basis for integrators and maintainers. It also provides an image of consistent forward momentum, suitable for any evolving library.
youtube_dl, the understated ally of Internet media archivists everywhere, uses a three-segment CalVer scheme, including full year, zero-padded month, and zero-padded day. The version is almost completely calendar-driven, except for a micro segment that is added in some technical contexts.
Despite the name, youtube_dl's scope is expansive. It supports extracting audio and video from a long, ever-expanding list of sites. Consider the rapid release cycle of supported services, and it becomes clear why the project has adopted CalVer to such a great degree.
pytz is the Python translation of the IANA/Olson timezone database, the database behind accurate times for all of computerdom. pytz uses a two-segment CalVer scheme, including full year and short month.
While Python has a history of "batteries-included" architecture, and the datetime module frequently mentions timezones, the core Python runtime does not include timezone information. This is because timezone updates do not follow a fixed schedule, and are subject to politics and legislative whim. Calendar versioning offers a date-stamped snapshot of an otherwise chaotic system.
The Teradata UDA client provides next-generation access to Teradata's data warehousing technologies.
Teradata's usage is notable not for the prominence of the technology
or company, but because there have been multiple releases in 2016
which were versioned as 15.10
. This may seem breaking at first, but
the meaning and utility is clear.
The library maintainers have crafted a resourceful hybrid of semantic versioning and calendar versioning. The YY.MM part of the version are used as a combined SemVer major version. That is, for new releases, the API of the library remains the same as it did in October 2015. Dependent code written since then is safe to upgrade. We will see the year and month segments update next time there is a breaking API change.
YY.MINOR.MICRO
- A broad library of
utilities supplementing the Python standard library.YYYY.MINOR.MICRO
- A leading Python IDE.YYYY.0M
- The premiere open-source
offering for solid 3D CAD modelling.YYYY.MM.DD_MICRO
- One of the
earliest and most cross-compatible NTFS access layers for Unix
systems.YYYY.MM.DD
- certifi is a wrapper around
Mozilla's certificate authority bundle, used for secure Internet
communication. Similar to pytz, certificate updates do not
follow a fixed schedule, but timely, dateable updates are critical
to security.
See the Users page for a growing list of CalVer users.
For those seeking straight answers to the version design question, the wait is over. In the end the decision is the project developer's, but here are the questions to be asking:
If you answered yes to any of these questions, CalVer's semantics may make it a strong choice for your project.