Devtools Projects Transitioning to CalVer Releases

Projects in the devtools space will be switching to CalVer releases over the next few weeks. This is a surprising change, so let’s get into what that means.

What

These are the projects that will be transitioning to CalVer:

We will use a YY.MM.MICRO version format. Thus, a release for March 2025 will be named 25.3.0, and if a patch (ie, non-feature) release is required for that release, it will be named 25.3.1, even if it is released in April, and the month will not increment until a new version with features or other significant changes is released.

Why

This is a bit of a change so let’s go over what we hope to accomplish with it.

  • Predictable, transparent release cadence

    With this, we are committing to time-based releases for all projects. While the exact frequency will vary between projects, each will have a release between one and three months after the last feature release.

  • Version number indicates the age of a release

    With CalVer, the age of a release can be trivially determined from the version number, instead of having to look up the release notes as at present.

  • Easier to translate versions between tools

    Many of our tools are interrelated. A consistent version scheme allows one to have a good idea of how related but independent tools are expected to work together.

How

Following this announcement, the next feature release in each project will be a CalVer release.

Feature releases will not happen more often than once a month, though patch releases may happen more often as needed. We will also make releases at least once every three months for each project.

Releases will still split out changes by category, including new features, bugfixes, documentation updates, announced deprecations, and removed features.

One of the things we are bringing with this change is an emphasis on fewer breaking changes / more emphasis on deprecation cycles and overlapping features. When something is deprecated, it will be called out in the release notes, along with replacement and how long the feature will remain in place.

What’s Next

As mentioned, this change will begin rolling out over the next few weeks. However, if you have any comments or concerns, please let us know.

16 Likes

@Qalthos this is a great news!

One thing to mention is that when recently i went through all the projects I noticed that there’s no info about versioning, releasing, no common changelog formation, etc. so would be nice to:

  • add the versioning info to at least README (maybe to docsites too).
  • make all changelog entries/tools for generating similar across all the projects: e.g. based on labels or whatever the majority of their developers prefer. In some projects, there are just all the commit messages listed w/o splitting to Major, minor, patch, etc. kind of changes in GH releases.

Thank you

4 Likes

@staff, can someone please move this to News & Announcements?

4 Likes

Done - I agree this is big enough news to email a lot of people about :stuck_out_tongue:

5 Likes

Has there been any discussion around using YYYY.MM.MICRO vs YY.MM.MICRO?

AWX has just released version 23 (SemVer, not CalVer) and I’m not sure that we will be able to make the transition to CalVer in time to avoid confusion.

Also I wonder if using YYYY makes it more obvious that this is a year.

1 Like

No need to worry YY was always the plan, no YYYY. We considered long one long time ago but YY won, also seen in popularity from other project’s.

I think @gundalow’s point is that YYYY makes it a lot clearer to distinguish CalVer from regular SemVer (since other Ansible ecosystem projects already use SemVer with major versions in a similar realm, like AWX). I agree using YYYY instead of YY would make this distinction clearer. But apparently that ship has already sailed.

5 Likes

Is there anything with calver that indicates possible breaking changes? Or should we from now on expect that every non-patch release is potentially breaking?

3 Likes

@tima you were talking about this at cfgmgmgtcamp this week, any thoughts on YYYY vs YY?

Continuing the discussion from Devtools Projects Transitioning to CalVer Releases:

It is a bit late for me to have an opinion if I really had much of one. When I talked about this at #cfgmgmtcamp, versions of the tools with YY had already been released. One of the ideas behind the move to CalVer is to form a relationship between the various ansible-dev-tools. These tools are independent from server components like AWX so it doesn’t really bother me that one uses YYYY and another YY. Not sure that was helpful.

1 Like