Moving to calendar based version numbers

Will Ezell

After talking about it for years, we are finally ready to move dotCMS to a calendar based versioning system ( rather than a "semantic" versioning system ( This means that instead of delivering software versioned as v5.3.5 or a v5.4.0, we will be shipping v20.10.1, e.g., the first version released in October 2020. This versioning system can also include patch versions - if version v20.10.1 needs a fix or a patch to it, even if delivered a month later, that version would then become v20.10.1.1, the last digit being the patch version. The example below is the 2nd release in October 2020, patch version 1.

Calendar Versioning


There are a lot of reasons for this change to dotCMS's versioning system and they can be summed up in a few distinct thoughts:

  • We always want to ship features and fixes to our customers as soon as they are ready.

  • We always want the downloaded version of dotCMS to be the best and latest version.

  • We want to indicate to users of the dotCMS system that the version they are running is potentially out of date and out of a supported life cycle.

Getting out of the business of versions

Version numbers should not drive decisions around what code makes it into a version. With semantic versioning, the next version number can become a head scratching discussion at the intersection of sales, marketing, support and engineering. Semantic versioning often caused us to make code choices of what to include or exclude from our next version based on the expected version number. Before you say, well, you are doing it wrong, hear me out.

We are a large user-facing piece of software. And we have many types of customers, from open source users, to self-hosted clients to 100% cloud based installations. We have seen and support 1000s (100,000s?) of valid use cases. We have many many customers with legacy data which we are trying not to break BUT at the same time, don’t want to dissuade them from upgrading. Because of these factors, we have struggled at times with the next version number. The questions we ask include:

  • Does a code change merit a new major version number? A new minor version number? Maybe an api response changed but that api was only consumed internally? Because we are open source, can we be sure it is only consumed internally?

  • Should we put a "big" fix that touches a lot of files into a patch version or do we hold the release of the big fix to wait for the next major/minor version?

  • When defining what forces a major version, do we care about the developers, the devops team or the end users? Should we tick the major release up because of an infrastructure change which makes the upgrade more difficult but changes nothing from an end -user's perspective? What will the CIO think after spending all that time doing the upgrade?

  • If we tick the major/minor version up to include a new feature, will that scare customers from upgrading even though nothing has changed in the pre existing code and APIs?

  • Here comes our next release, dotCMS 10.0! Now we need to cram features x,y and z into it as well so they can be marketed/messaged together with the major version.

  • And on and on.

These questions happen inevitably. My guess is that a semantic versioner would argue that if there are any questions, you should aggressively tick up the larger of the version points you are debating to be on the safe side, e.g. release 5.4.0 rather than a 5.3.5 or 6.0 vs. a 5.4.6. That is fine if you are an evergreen desktop app - I’m on chrome what? 83.0.4103.116? Fine. I’d argue that if you use such aggressive semantic versioning, version numbers quickly pile up and reach a point that loses meaning for anyone not on the dev team and no one will know how out of date the software is without consulting documentation.

These thoughts might be different for (evergreen) apps, or developer-consumed libraries, or for 100% SaaS solutions that offer a predefined set of rest apis. I can see how semantic versioning works in those cases. For us, I believe semantic versioning would ALWAYS present a business challenge for us in balancing code and the competing business goals around any major and minor release. Moving to a calendar based versioning system automatically decouples the development and engineering teams from all that… business.

Keeping up to date

Keeping our customers running on the best and latest versions of dotCMS is one of our major business goals. If you have been following, you’ve noticed that the dotCMS release cycle has sped up considerably - we have been putting out a release every 3 weeks - save for when we ticked up our minor version number. Like the rest of the development universe we have been working hard on moving towards continuous integration and delivery, where our dotCMS installations are always up to date. Calendar based version numbers convey direct information to customers and lets every dotCMS user know if the version they are running is up to date or antiquated - without having to search or triangulate changelogs or external references.

Breaking Changes are for the Changelog

As we have experienced, breaking changes whether known or unknown can happen with any version update, even sometimes in patch releases. Inevitably, when deciding on upgrading to a new version, the only place that will capture what has changed and what could possibly go wrong is the dotCMS changelog. The changelog coupled with the links to the issue cards should be the go to place to understand the changes that have been made to the dotCMS code base and what effort is required to update your dotCMS instance. Semantic versioning offers some insight into the levels of effort required to upgrade but too often represents an under or over estimation of the challenges a new version brings.

Supported Versions - or how to know which version to run?

Release Version

dotCMS plans to release a new version of dotCMS every 3-4 weeks and all dotCMS internal sites will automatically be updated to the latest version. These release versions provide customers access to new features and each release version will be supported in terms of troubleshooting for no less than 3 months after their release date.

LTS Version

Every 6 months, dotCMS will deem a version an LTS (Long Term Supported) version. An LTS version will receive backported fixes and patches for up to a year after its release date, though it will not receive any of the new features that are part of the later versions.

What Version to Use?

We recommend the release version for customers who want to take advantage of the newest features or for customers who are in an implementation phase and plan to launch some time in the future - after launch, they might want to switch to an LTS version.

We recommend the LTS version if your company has policies that don’t allow for frequent upgrades or restrict using non-LTS software. Additionally, you might want to use an LTS version if you are using dotCMS in secondary products that either don’t require newer dotCMS features or if you don’t have enough resources to keep dotCMS updated.

Will Ezell
Chief Technology Officer
October 08, 2020

Recommended Reading

Mastering the New Universal Visual Editor in dotCMS: A Technical Deep Dive for Developers

Explore dotCMS's Universal Visual Editor, merging WYSIWYG simplicity with headless CMS flexibility. This tool offers drag-and-drop editing, inline content editing, and NoCode tooling for seamless omni...

Benefits of a Multi-Tenant CMS and Why Global Brands Need to Consolidate

Maintaining or achieving a global presence requires effective use of resources, time and money. Single-tenant CMS solutions were once the go-to choices for enterprises to reach out to different market...

Headless CMS vs Hybrid CMS: How dotCMS Goes Beyond Headless

What’s the difference between a headless CMS and a hybrid CMS, and which one is best suited for an enterprise?