Pre-1.0 collection upgrade policy within a stable ansible series

[abadger]

Background

For ansible-2.10.z, 2.11.z, etc we're going to make releases of ansible that strive to be backwards compatible. 2.10.0 is backwards compatible with 2.10.1, 2.10.99, etc. 2.11.z can introduce backwards incompatibilities.

We're going to do this by requiring collections follow the semantic versioning specification and then we'll key off of their version number. The semver spec says that 1.0.0 will be backwards compatible with any other 1.y version... even 1.999.0 would be backwards compatible with 1.0.0. 2.0.0 would mark the collection as being backwards incompatible. So if we ship 1.0.1 in ansible-2.10.0. We'll ship upgrades to the collection that are 1.y throughout the ansible-2.10.z lifetime. But we'll never ship 2.y of the collection.

There is an ambiguity with versions before 1.0. The semver spec says:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Problem

What should be the policy for shipping updates to pre-1.0 collections? If we want 2.y to be compatible, the spec says that we cannot rely on the 0. version numbers giving us any information about potential backwards incompatibilities.

Possible policies

1. Take any upgrades all the way through 1.y. Warn that this collection could be backwards incompatible in the documentation.

• Benefit: Gets us to 1.0 sooner.
• Con: Burden falls on the user to know that this particular collection has an unstable API

2. Do not allow collections with versions less than 1.0 into ansiible.

• Con: At least for ansible 2.10, this conflicts with the desire to produce a release that has all of the content that was in ansible-2.9.

3. Do not upgrade those collections for the length of 2.10.

• Benefit: End user gets a stable interface
• Con: End user will have no hope of any bugs in the collection being fixed before 2.11.

4. Have an additional versioning policy beyond semver and ask collection owners to follow it:

• For 0.y.z, if backwards incompatibilities exist in a new release, y must be bumped. Otherwise, bump z.
• Benefit: We can take updates automatically
• Con: We already wonder if the collection owners will follow semver. An additional policy beyond that may be even harder to get them to follow.

5. Do not upgrade automatically but allow collection owners to manually tell us to update.

• Collection owners can submit a PR to https://github.com/ansible-community/ansible-build-data/ to manually ask for their 0.y.z collection to be updated in the new Ansible release. They should state that the update is backwards compatible.
• Benefit: Give the ability to update for new bugfixes
• Con: More work for the collection owners. More work for the ansible release team.

[felixfontein]

I currently prefer 5. This keeps it relatively stable, and pushes most of the work to collection owners if they didn't manage to finish a 1.0.0 before collection versions are collected for ACD. (I also hope the list of such collections will be short..)

[abadger]

Yeah, 5 is starting to feel like the right thing to me too...

[abadger]

The decision today was:

#info we decided on option 5: allow upgrades in 0.y.z, but collection owner must request that manually

[abadger]

I'll close this ticket with the PR implementing the change.

[abadger]

ansible-2.10.0 shipped with all collections at either 1.0.0 or later. One of the policies for inclusion of new collections in future versions of ansible is that the collection needs to be at 1.0.0 or later. Between the two of these, the policy meant that no code changes were needed. Closing this ticket.