[RESOLVED] Versioning and deprecation

[gundalow]

SUMMARY

• In ansible/ansible:

  • There is a single version number which is over everything shipped in Ansible
  • Doesn't use semver, uses X.Y (ie 2.9) as the major number
  • Deprecations are done over 4 versions (~ 2 years)

• In Collections:

  • Can be versioned and released independently to Ansible
  • MUST use semver (Semantic Versioning) <https://semver.org/>_

Use-cases

Users

• As a user I want to know if an upgrade to a Collection may including breaking changes
• As a user I want to be able to install a newer Collection, even if it's included in ACD
• As a user I want to know if a collection will work with the version of ansible I’ve standardized on

Contributors

• As a Contributor I may want to take advantage of new functionality in ansible-base, and therefore set dependencies on that
• As a Contributor I want to know when I can introduce breaking changes, and when I can't (freeze window)
• As a Contributor I want to specify the required version of Ansible

Maintainers

• As a Maintainer I want to release a Collection without an Ansible version increment
• As a Maintainer I want to release a Collection without an ACD version increment
• As a Maintainer I want to detail which minimum versions of Ansible my Collection requires

Community Team

• As a member of the Community Team, we need to know which commit of a Collection to pull into ACD

Deprecation Cycle

• As a user I want to know that Deprecation notices WILL be honored
• As a maintainer I want to know when I can act on the removed_in_version: 2.14 notices previously given

Proposal Versioning

• All collection owners should follow semver versioning standards for versioning their collections.
  • https://semver.org/
    • Given a version number MAJOR.MINOR.PATCH, increment the:
      • MAJOR version when you make incompatible API changes,
      • MINOR version when you add functionality in a backwards compatible manner, and
      • PATCH version when you make backwards compatible bug fixes.
    • Versioning should be based on APi changes of collections not API changes of ansible-base
    • Example: The first collection created for some content can start with the version number like 1.0.0
• Galaxy and AH tooling will only enforce semver at the import time to make sure proper versioning standards are defined and followed. There will be no validation if versioning is followed in principles of API changes in the collection.
• Ansible Collection owner has to specify metatag in collection that will specify which ansible-base version and above the collection is supported e.g. meta/($somefile_tbd). It will have some line like requires_ansible: '>=2.10' - implemented by Collection redirection/tombstoning #67684
• ACD versioning will be based on current established standards of ansible-base there are no changes proposed to that versioning standard

Proposal Deprecation

?

[felixfontein]

I'm strongly for collections following semver. Even though that means that collections such as community.general will soon have version numbers in the range of Firefox/Chrome :)

I'd like that collections still use version_added to indicate in which collection version a feature first appeared.

Deprecation: that's a tough one. There have been some advocates for deprecation by date (see f.ex. ansible/ansible#68177), though I guess collections can also deprecate by version. (From my point of view, there's no reason why not.) Every collection should be able to decide by themselves.

I guess the harder question is how big collections such as community.general and community.network should be versioned. If we don't want to stick to major version changes on every release, we need some branching / backporting to make sure no breaking changes to into minor / patch releases.

[felixfontein]

Proposal A for community.general and community.network:

1. master is current development branch
2. regularly release (once every 1-3 months?): new major version number
3. major release gets branch
4. bugfixes and new features (which don't break backwards compatibility) can be backported
5. only current major release branch is up for backporting
6. we only do major and minor versions; patch is only used for hotfixes (like f*ckup during release which needs to be fixed quickly)
7. minor version releases happen every 14 days

[felixfontein]

Proposal B for community.general and community.network:

1. master is current release branch
2. regularly release every 14 days with minor version increments
3. patches are only used for emergencies (as above)
4. PRs which break backwards compatibility in some way are not merged until a new major version comes up (every 2-6 months?)
5. Alternatively: backwards compatibility breaking PRs end up in a special branch

[samccann]

Some details of this are available in ansible/ansible#68594

[abenokraitis]

Let's split out versioning from deprecation if we can first. Please refer to the proposed versioning document at ansible/ansible#68594 for more info.

[felixfontein]

Based on the official proposal in ansible/ansible#68594 and @sivel's explanation, here's a modified Proposal A:

Proposal A' for community.general and community.network:

1. master is current development branch
2. regularly release (once every 6): new major version number
3. major release gets branch
4. bugfixes and new features (which don't break backwards compatibility) can be backported
5. only current major release branch is up for backporting features
6. all active release branches (usually 4) are up for backporting bugfixes (maybe limit to critical/security bugfixes after ~12 months, to reduce workload for RMs?)
7. we only do major and minor versions; patch is only used for hotfixes (like f*ckup during release which needs to be fixed quickly)
8. minor version releases of the latest release branch happen every 2 weeks
9. patch releases of active (but not the latest) release branches happen when needed

[Andersson007]

• I'd exclude new features (which don't break backwards compatibility) from proposal A p.4 in order to keep released stuff more stable (and p.5 resp). Anyway, major versions will be released fast enough (relatively to ansible.ansible), so, there's no need to wait for new features for 4-6 months as it was.
• minor releases every 2 weeks. Won't it be overwhelming for RMs in case of backporting features as well? If new features are not backported, this interval will be ok IMO.

[Andersson007]

about release terms (min and max boundaries IMO):
X.x.x: 6 months - 1 year
x.X.x: 1 - 2 months (new features, modules)
x.x.X: 1 - 2 weeks (fixes)

[Andersson007]

Copied from the email

TBO, the terminology is a big source of confusion.

Regarding https://semver.org/ :
Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

And i’ve always thought that:

• X.x.x is major
• x.X.x is minor
• x.x.X is patch
  (and it looks similar to what semver.org is talking about)

However, regarding https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html ,
New modules, plugins, features and bugfixes will always be integrated in what will become the next major version of Ansible.

So, the statement above implies that 2.8, 2.9, 2.10 etc. are major releases.
And it’s practically true, because, as we know, in ansible/ansible «incompatible API changes», e.g. deprecations, happen in x.X.x release.
If x.X.x is major, x.x.X is minor? What is X.x.x then?

Maybe Ansible base follows its own versioning rules shaped by historical reasons.

Anyway, first of all, would be good to admit something clear and ubiquitous
about the terminology for ansible-collections (and then engrave it in the documentation, would be perfect).
After that, we can go further with discussing branches and other release-related stuff.
It’s important to be sure that we have the same understanding of any notions we’re going to discuss.

So, following the rules of the semver,

• major release: X.x.x (e.g. 2.x.x): deprecations, other incompatible API changes
• minor release: x.X.x (e.g. x.1.x): new modules, plugins, backwards compatible features, bugfixes, security patches, etc.
• patch release: x.x.X (e.g. x.x.7): backwards compatible bugfixes, security patches

Any ideas? :)

[sivel]

However, regarding https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html ,
New modules, plugins, features and bugfixes will always be integrated in what will become the next major version of Ansible.

That isn't technically true, and the version of a collection is not intended to be linked to a version of ansible-base. The "ansible" package will bundle some collections, but that is a convenience, and users can still independently install collections outside of that, and we fully expect users to install newer versions of collections than what "ansible" has bundled. The explicitly installed version will have precedence as long as it's installed.

However, with that being said, collections will be able to state what ansible-base versions they work with.

We have stated that ansible-base doesn't follow semver. We may change that at some point in the future, but no immediate plans to do so.

[Andersson007]

sorry for closing:( something happend to my browser.

[felixfontein]

We have stated that ansible-base doesn't follow semver. We may change that at some point in the future, but no immediate plans to do so.

Maybe start with 3.0.0, whenever that's up? :)

[Andersson007]

@felixfontein interesting suggestion!:)
Anyway, our first aim is to decide something for collections.
Maybe ansible-base will follow the collections since 3.0 after we show a "right" approach and good example how to do things better:)

[gregdek]

I'll have an updated proposal for deprecation policy by next Thursday, May 7th.

[gregdek]

A gist for comment:

https://gist.github.com/gregdek/52e6669421d3f65cded51862e16ad0e9

[gregdek]

Note that much of the basis for this is found in the Fedora Project's processes for orphaning and/or retiring packages.

[gundalow]

Done

[felixfontein]

See https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#versioning-and-deprecation