Release Ansible versioned with semver

[yajo]

Proposal: better versioning

Author: Jairo Llopis <@yajo>

Date: 2020-06-03

• Status: New
• Proposal type: process
• Targeted release: 3.0
• Estimated time to implement: 1 minute.

Motivation

ansible/ansible#44286 explains it pretty fine, but I think the proposer was somehow ranting.

However, there's part of good motivation behind it. The fact that when you upgrade from ansible 2.n to 2.n+1 you can get backwards incompatibilities is very awkward.

Problems

When working downstream on playbooks, this made me several times "raise my eyebrows" like "what? this playbook was working yesterday... what happened?". Then, I had to realize later that my distro just upgraded a minor Ansible version. Possibly the packager didn't know that a "minor" in the normal packaging world is "major" for Ansible.

Some examples that come to my mind:

• In Ansible 2.12, the python interpreter discovery will change
• In Ansible 2.5, include and import behavior changed and caused quite a lot of pain.

Ansible expects collections to use semver, while Ansible itself doesn't use it. Quoting from the overview README:

• In ansible/ansible:
  • Doesn't use semver, uses X.Y (ie 2.9) as the major number
• In Collections
  • By convention, Galaxy requires a Collection to follow semver (Semantic Versioning)

This makes more frustrating the collection development process.

Solution proposal

Adopt semver:

1. If a release has any kind of backwards incompatibility, do a new major release.
2. If a release has enhacenments (or new features), or when old features are deprecated but still work as before, do a new minor release.
3. If a release has just bug fixes, do a new patch release.

For example, according to the roadmap for Ansible 2.10:

The 2.10 release of Ansible will fundamentally change the scope of plugins included in the ansible/ansible repository, by moving much of the plugins into smaller collection repositories that will be shipped through https://galaxy.ansible.com/

That's big enough for releasing Ansible 3.0.

Also, Ansible 2.12 was meant to change the default python interpreter. That's big enought for releasing Ansible 4.0.

... and so on.

Documentation

A little mention in the docs for Ansible 3.0 (old 2.10) release: "from now on, we use semver" should be enough.

Anything else?

Yes, thanks for you great work!

[felixfontein]

For 2.10, it is probably too late. But I'd also like to see this happen. Maybe the next version after Ansible 2.10?

Also, there are two different projects involved here: ansible-base (which is ansible/ansible), and ansible (which is ansible-base + collections).

[gundalow]

@yajo Thank you for taking the time to create a proposal on this.

This is something that has been talked about a lot, especially in the run up to Ansible 2.10 which has collections, and discussions about if it should be called Ansible 3.0.

This is something we should have some public discussion around. Lets revisit this two months after Ansible 2.10 has been released.

[yajo]

Ansible 2.10 was released more than 2 months ago. May this discussion be brought to the table again?

[felixfontein]

We discussed this at today's community meeting and decided to release the Ansible package with semantic versioning starting with the next major release. I.e. instead of ansible-2.11, there will be ansible-3.0.0.

This does not affect ansible-base / ansible-core. They will stick to the current versioning scheme for some more time.

Please note that using semver requires us to release 2-3 major releases per year, since we have to include breaking changes from collections from time to time.

[ssbarnea]

Why not using CalVer instead? Here are few links that should help.

• https://calver.org/
• https://snarky.ca/why-i-dont-like-semver/
• https://www.bernat.tech/version-numbers/
• https://sbarnea.com/posts/semver-vs-calver/ my own, better read the other links.

PS. Before arguing read the stories, you will likely discover that what looks perfect on paper may not prove not so be clear to use in the end.

[felixfontein]

The difference between CalVer and SemVer is that SemVer is properly defined, and CalVer (especially on https://calver.org/) is not really defined, but leaves a lot to imagination. So if you want to propose CalVer, you should really propose a concrete scheme so we know what you are talking about. I assumed after the discussion on IRC yesterday that it was more strictly defined, but after reading the page more thoroughly, I am just more confused. I don't think it is. If you use YEAR.MONTH.increment (as https://www.bernat.tech/version-numbers/ suggestes is meant by CalVer), it is not compatible with SemVer anymore (but that was claimed on IRC yesterday) - except if we limit to one major release per year. Which pretty surely won't happen.

I am personally against any scheme which not also conforms to SemVer.

[ssbarnea]

I was having a combination of SemVer with CalVer more like YY.MAJOR.MINOR.PATCH in mind, which in SemVer world seams to be called GENERATION (or release).

Apparently there is a slight chance for SemVer spec to be extended to allow it, check semver/semver#213 (comment) -- If that happens we may have a solution that covers both.

As few agued if if you see the YY.MM counting as MAJOR, you could claim is semantic. I think that nobody supporting CalVer is against respecting SemVer meanings, is more about splitting major part into two in order to address the calendar aspect.

I am ware that a project could go for 201 to represent year 2020, release 1, or for 2001 to represent year 2020 month 1 and fully respect semver, but it does not take much time to realise what kind of confusions this will generate. I doubt anyone ever adopted something like this.

[felixfontein]

Splitting up the major part into two numbers is NOT SemVer according to the current spec. There is a lot of code and assumption in user's heads out there that major is just the first part, so doing something differently would create a lot more confusion. If we don't strictly adhere to the current SemVer spec, we can also keep the old versioning system IMO where the first two components are the major part, instead of inventing something new.

[bcoca]

closing as the 'ansible' community package is now using semantic versioning.

[felixfontein]

I guess someone needs to create a new proposal for ansible-core then...