Versioning and Release Strategy for Ansible Engineering Maintained Certified Collections

The following knowledgebase article provides supportability guidance for Certified Ansible content that is fully supported as part of the Ansible Automation Platform subscription. These Ansible Content Collections are a subset of the larger certified Collection library housed on Ansible Automation Hub. These guidelines apply specifically to the content labeled as maintained and supported by Red Hat Ansible. Guidance is provided for support life cycles of content, versioning strategies, and differentiating feature releases (FR) from product maintenance releases (MR) as part of the subscription.

Release Rationale and Contributing

The following approach below strikes a balance between two historically competing goals by content developers:

1. Ansible content developers desire to rapidly release new functionality and version collection releases based on a standards-based version specification without any support implication tied to the version number.

2. Ansible content users desire to identify a production-grade collection release that will receive bug and security fixes without breaking changes. Such a version should have a well-defined support duration and the availability of such versions should overlap allowing for a window of transition.

With the Ansible collections subsystem fully supported for content, most content (modules, plugins, etc.) no longer needs to be stored in a single GitHub repository. Given that the content is now no longer in a single upstream repository, versioning is no longer the responsibility of Ansible, but now the responsibility of the content authors and maintainers. Furthermore, collections may be released at predictable intervals and cadences, while others may only be released if required. That being said, Ansible-maintained collections still welcome community contributions, but the criteria for inclusion may be higher than other community workgroups. Refer to the Ansible Community Guide's section on "Contributing to Ansible-maintained Collections" for more information on how to contribute upstream.

Collection Versioning Strategy

Each certified collection maintained by Ansible follows Semantic Versioning 2.0.0 (https://semver.org/), for example:
Given a version number MAJOR.MINOR.PATCH, the following is incremented:

1. MAJOR version: when making incompatible API changes (see Feature Release scenarios below for examples)

2. MINOR version: when adding features or functionality in a backward-compatible manner, or updating testing matrix and metadata (deprecation)

3. PATCH version: when adding backward-compatible bug fixes or security fixes (strict).

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

The first version of a generally available supported collection on Ansible Automation Hub shall be version 1.0.0. NOTE: By default, all newly created collections may begin with a smaller default version of 0.1.0, and therefore a version of 1.0.0 should be explicitly stated by the collection maintainer.

Supportability Metadata for Collections

Previously (before collections), supportability metadata was located in the module itself. Now that supportability is at the collection level, and new construct had to be created. Therefore, the /meta/runtime.yml file is utilized. This file contains information about deprecation, minimum/tested Ansible versions, and redirection rules for backward compatibility in older Ansible releases.

NOTE: There is no longer any metadata associated with tagging collections as supported, certified, or community as was done in previous Ansible releases (2.9 and older). All content on Ansible Automation Hub is deemed either certified or validated with additional clarification on what level of support is applicable, as well as which entity supports it.

Release Types

• Feature Releases (FRs): (aka latest release) Feature releases are periodic. For supported collections, the target release cadence for minor and major releases is 4 weeks. Feature release with a patch change can happen as needed. Feature releases are only supported until the next feature release is available.

• Maintenance Releases (MRs): When an existing feature release of supported content is identified as a maintenance release, it will be supported with bug and security fixes for 24 months. Maintenance Releases are intended for customers with a desire to use a stable version of a collection for up to 24 months. Maintenance release will receive bug and security fixes for 24 months after identified. Maintenance Release will not receive new functionality or breaking changes.

• Betas/Pre-releases: These releases are designed to satisfy developer workflow requirements and are not intended to be used in production environments.

Feature Release (FR) Scenarios

New content is added to an existing collection

Assuming the current release is 1.0.0, and a new module is ready to be added to the collection, the minor version would be incremented to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.

New feature to existing plugin or role within a collection (backward compatible)

Assuming the current release is 1.0.0, and new features for an existing module are ready for release. We would increment the MINOR version to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.

Bug fixes or security fixes to existing content within a collection

Assuming the current release is 1.0.0 and a bug is fixed before the next minor release, the PATCH version would be incremented to 1.0.1. The patch indicates only a bug was fixed within the current version. The PATCH release does not contain new content, nor was functionality removed. Bug fixes may be included in a MINOR or MAJOR feature release if the timing allows, eliminating the need for a PATCH dedicated to the fix.

Breaking change to any content within a collection

Assuming the current release is 1.0.0, and a breaking change (API or module) is introduced for a user or developer. The MAJOR version would be incremented to 2.0.0.

Examples of breaking changes within a collection may include but are not limited to:

• Argspec changes for a module that requires either inventory structure or playbook changes.

• A change in the shape of either the inbound or returned payload of a filter plugin.

• Changes to a connection plugin that require additional inventory parameters or ansible.cfg entries.

• New functionality added to a module that changes the outcome of that module as released in previous versions.

• The removal of plugins from a collection.

Content removed from a collection

Deleting a module or API is a breaking change. Please see the ‘Breaking change (any) section for how to version this.

A typographical error was fixed in the documentation for a collection

A correction to the README would be considered a bug fix and the PATCH incremented. See ‘Bug fix’ above.

Documentation added/removed/modified within a collection

Only the PATCH version should be increased for a release that contains changes limited to revised documentation.

Maintenance Release (MR) Scenarios

The support plan for product and Certified collections needs to be available to Ansible customers.
Every ~18 months an existing Feature Release version will be identified as a Maintenance Release. An MR version of a collection will only receive bug and security fixes.

• The supported ansible-base version of an MR collection release will not change. Care needs to be taken to ensure an MR does not require an unsupported version of ansible-base. If faced with this situation, an MR release may need to be identified before the 18-month target.

• MR collection versions will not receive new functionality unless required for a bug or security fix.

• The asserted host or downstream device’s supported version claimed by an MR collection version will not change.

• A MR collection release will be supported for 2 years. This allows for a maximum 6-month window for a customer to transition between MR versions of a collection.

• MR collection releases are only guaranteed to be available on the automation hub.

• An MR collection version is identified by a unique, non-changing MAJOR.MINOR. This leaves the PATCH available for security and bug-related fixes.

• When a customer identifies an MR collection version is locked to an unsupported or now unavailable dependency, this will be addressed on a case-by-case basis, with the general approach being to encourage the customer to use a later version of the collection.

Alphas, Betas, and Other Pre-GA Releases

If there are pre-release or Beta versions of collections needing versioning, please utilize the hyphen in the version when leading up to a release as specified by the semantic versioning specification. For example, 2.0.0-rc.1 would precede the final 2.0.0 version. 0.1.3-1 would precede the 0.1.3 release.