Complete text and better reading experience (10min) : Designing a version — Sedimental
CalVer is a versioning convention based on your project’s release calendar, instead of arbitrary numbers.
For maintainers, versioning allows us to specify precise dependencies within an ever-expanding ecosystem. For sellers and promoters, a project’s version is a dynamic part of a brand. For all of us, versioning lets us reference the past while upgrading to the future.
This date-based approach has come to be called Calendar Versioning, or CalVer for short.
CalVer leverages natural understanding
People are calendar-oriented. Practically, it’s just easier to remember that a library was causing a live issue back in 2013 than it is to remember that up until version 1.6.18 that library had a lot of bugs.
Furthermore, in long-term development, releases pile up and increasingly large major versions blur together. Browser versions have been rendered meaningless. But the calendar is one construct where numbers increase and cycle regularly. Leveraging that natural understanding anchors otherwise arbitrary versions.
CalVer has better semantics
Ironically yes.
“Semantic” Versioning is all relative. One developer’s 1.0.0 is another’s 0.0.1alpha. As authors, we try to ignore this and write others off as wrong. But as clients, we make snap judgments, and SemVer lets us forget and pretend. Calendar versioning is absolute and neutral, with practical advantages to boot.
As application developers adding functionality, evaluating a new library means ascertaining maintenance status, usually by looking at the most recent release date. CalVer puts us in the ballpark right away. As maintainers depending on many libraries, calendar versioning allows us to look at the dependency list and quickly ascertain which libraries are good candidates for updating. CalVer even lets us take that a step further, with date-based deprecation.
Many might not realize it, but the oh-so ubiquitous Ubuntu is in fact calendar versioned. For example, version 15.04 came out in April, 2015. It gets better when you remember Long-Term Support. Ubuntu’s LTS support lasts for five years. So, 14 + 5: Ubuntu 14.04’s end of life will be in 2019. You don’t have to look anything up. It’s all right there in the CalVer semantics.4
CalVer protects projects
If you care about the future of the project, then guard it against one of the worst fates: the fatuous 2.0. Give your project a future. Guard against the learned expectation of 2.0 or death.
A 1.x always carries one advantage over a 2.0: the code is deployed and working. Avoid contempt for past decisions and current users. In engineering, utility is half of correctness.
SemVer is set up so that every major release implies a minimum threshold of change. If the project is founded on and aiming for correctness, fewer and fewer changes are required. Donald Knuth embraced this in the extreme by having TeX’s version approach π asymptotically. Suffice to say with CalVer, you are safe to add as much or as little functionality as needed.
Too often projects become a victim of versioning. New projects end up masquerading as new versions. D3 could have been Protovis 2.0, but instead, a successor was created. Both projects coexisted and we are all the better for it. Same with characteristic and attrs. Successors and CalVer protect projects and do justice by clients and code.
Compared to SemVer
Some comparisons are inevitable. SemVer, hosted at semver.org, is a big name in software versioning conventions. CalVer combines well with incremental-number schemes, so it’s not strictly a competition. That said, here is how CalVer outshines SemVer.
CalVer integrates objective, intuitive calendar dates.
⊠ SemVer subjectively increments numbers.
CalVer encompasses real-world usage through a formal vocabulary.
⊠ SemVer imitates the form of a specification, albeit a confrontational one. Unlike real specifications, SemVer lacks objective verifiability, exemplars, or reference implementations.
CalVer makes maintenance easier through powerful, objective semantics. Look at a library’s version number, immediately know how recent your copy. Compare across libraries, checking that dependencies are in sync. Deprecate versions based on time.
⊠ SemVer has Tom Preston-Werner’s semantics.
CalVer’s use of release dates allows for automatable, immutable versions on which everyone can agree.
⊠ SemVer introduces one more place a bug can enter a projects. Versions only go up, and a release which violates SemVer guidelines cannot be undone. That pressure means more projects perpetually stuck in 0.x.
The list goes on, but the message is clear. There is an alternative to SemVer, and it’s about time!
When to use CalVer
If both you and people you don’t know use your project seriously, then use a serious version. Luckily, the decision on whether to use CalVer for that version is easier than ever:
- Does your project feature a large or constantly-changing scope?
- Large systems and frameworks, like Ubuntu and Twisted.
- Amorphous sets of utilities, like Boltons.
- Is your project time-sensitive in any way? Do other external changes drive new project releases?
- Business requirements, such as Ubuntu’s focus on support schedules.
- Security updates, such as certifi’s need to update certificates.
- Political shifts, such as pytz’s handling of timezone changes.
If you answered yes to any of these questions, CalVer’s semantics make it a strong choice for your project.
