212 lines
9.6 KiB
ReStructuredText
212 lines
9.6 KiB
ReStructuredText
.. _release_and_maintenance:
|
|
|
|
Release and maintenance
|
|
=======================
|
|
|
|
.. contents:: Topics
|
|
:local:
|
|
|
|
.. _release_cycle:
|
|
|
|
Release cycle
|
|
`````````````
|
|
|
|
Ansible is developed and released on a flexible 4 months release cycle.
|
|
This cycle can be extended in order to allow for larger changes to be properly
|
|
implemented and tested before a new release is made available.
|
|
|
|
Ansible has a graduated support structure that extends to three major releases.
|
|
For more information, read about the :ref:`development_and_stable_version_maintenance_workflow` or
|
|
see the chart in :ref:`release_schedule` for the degrees to which current releases are supported.
|
|
|
|
If you are using a release of Ansible that is no longer supported, we strongly
|
|
encourage you to upgrade as soon as possible in order to benefit from the
|
|
latest features and security fixes.
|
|
|
|
Older, unsupported versions of Ansible can contain unfixed security
|
|
vulnerabilities (*CVE*).
|
|
|
|
You can refer to the :ref:`porting guides<porting_guides>` for tips on updating your Ansible
|
|
playbooks to run on newer versions.
|
|
|
|
.. _release_schedule:
|
|
|
|
Release status
|
|
``````````````
|
|
|
|
=============== ========================== =================================================
|
|
Ansible Release Latest Version Status
|
|
=============== ========================== =================================================
|
|
devel 2.8 (unreleased, trunk) In development
|
|
`2.7`_ 2.7.0 (2018-10-04) Supported (security **and** general bug fixes)
|
|
`2.6`_ 2.6.5 (2018-09-28) Supported (security **and** critical bug fixes)
|
|
`2.5`_ 2.5.9 (2018-09-10) Supported (security fixes)
|
|
`2.4`_ 2.4.6 (2018-07-05) Unsupported (end of life)
|
|
`2.3`_ 2.3.3 (2017-12-20) Unsupported (end of life)
|
|
`2.2`_ 2.2.3 (2017-05-09) Unsupported (end of life)
|
|
`2.1`_ 2.1.6 (2017-06-01) Unsupported (end of life)
|
|
`2.0`_ 2.0.2 (2016-04-19) Unsupported (end of life)
|
|
`1.9`_ 1.9.6 (2016-04-15) Unsupported (end of life)
|
|
<1.9 n/a Unsupported (end of life)
|
|
=============== ========================== =================================================
|
|
|
|
.. note:: Starting with Ansible-2.4, support lasts for 3 releases. Thus Ansible-2.4 will receive
|
|
security and general bug fixes when it is first released, security and critical bug fixes when
|
|
2.5 is released, and **only** security fixes once 2.6 is released.
|
|
|
|
.. Comment: devel used to point here but we're currently revamping our changelog process and have no
|
|
link to a static changelog for devel _2.6: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
|
|
.. _2.7: https://github.com/ansible/ansible/blob/stable-2.7/changelogs/CHANGELOG-v2.7.rst
|
|
.. _2.6: https://github.com/ansible/ansible/blob/stable-2.6/changelogs/CHANGELOG-v2.6.rst
|
|
.. _2.5: https://github.com/ansible/ansible/blob/stable-2.5/changelogs/CHANGELOG-v2.5.rst
|
|
.. _2.4: https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md
|
|
.. _2.3: https://github.com/ansible/ansible/blob/stable-2.3/CHANGELOG.md
|
|
.. _2.2: https://github.com/ansible/ansible/blob/stable-2.2/CHANGELOG.md
|
|
.. _2.1: https://github.com/ansible/ansible/blob/stable-2.1/CHANGELOG.md
|
|
.. _2.0: https://github.com/ansible/ansible/blob/stable-2.0/CHANGELOG.md
|
|
.. _1.9: https://github.com/ansible/ansible/blob/stable-1.9/CHANGELOG.md
|
|
|
|
.. _support_life:
|
|
.. _methods:
|
|
|
|
.. _development_and_stable_version_maintenance_workflow:
|
|
|
|
Development and stable version maintenance workflow
|
|
```````````````````````````````````````````````````
|
|
|
|
The Ansible community develops and maintains Ansible on GitHub_.
|
|
|
|
New modules, plugins, features and bugfixes will always be integrated in what will become the next
|
|
major version of Ansible. This work is tracked on the ``devel`` git branch.
|
|
|
|
Ansible provides bugfixes and security improvements for the most recent major release. The previous
|
|
major release will only receive fixes for security issues and critical bugs. Ansible only applies
|
|
security fixes to releases which are two releases old. This work is tracked on the
|
|
``stable-<version>`` git branches.
|
|
|
|
.. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions
|
|
are only supported for two releases with the first stage including both security and general bug
|
|
fixes while the second stage includes security and critical bug fixes
|
|
|
|
The fixes that land in supported stable branches will eventually be released
|
|
as a new version when necessary.
|
|
|
|
Note that while there are no guarantees for providing fixes for unsupported
|
|
releases of Ansible, there can sometimes be exceptions for critical issues.
|
|
|
|
.. _GitHub: https://github.com/ansible/ansible
|
|
|
|
.. _changelogs_how_to:
|
|
|
|
Changelogs
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Older versions logged changes in ``stable-<version>`` branches at ``stable-<version>/CHANGELOG.md``. For example, here is the changelog for 2.4_ on GitHub.
|
|
|
|
We now generate changelogs based on fragments. Here is the generated changelog for 2.6_ as an example. When creating new features or fixing bugs, create a changelog fragment describing the change. A changelog entry is not needed for new modules or plugins. Details for those items will be generated from the module documentation.
|
|
|
|
Creating New Fragments
|
|
----------------------
|
|
|
|
Create a new file with a unique and descriptive name in ``changelogs/fragments/`` that ends in ``.yaml`` such as ``user-40696-backup-shadow-file.yaml``
|
|
|
|
A single changelog fragment may contain multiple sections but most will only contain one section. Here are the valid sections and a description of each:
|
|
|
|
**major_changes**
|
|
Major changes to Ansible itself. Generally does not include module or plugin changes.
|
|
|
|
**minor_changes**
|
|
Minor changes to Ansible, modules, or plugins. This includes new features, new parameters added to modules, or behavior changes to existing parameters.
|
|
|
|
**deprecated_features**
|
|
Features that have been deprecated and are scheduled for removal in a future release.
|
|
|
|
**removed_features**
|
|
Features that were previously deprecated and are now removed.
|
|
|
|
**bugfixes**
|
|
Fixes that resolve issues. If there is a specific issue related to this bugfix, add a link in the changelog entry.
|
|
|
|
**known_issues**
|
|
Known issues that are currently not fixed or will not be fixed.
|
|
|
|
Most changelog entries will be ``bugfixes`` or ``minor_changes``. When writing a changelog entry that pertains to a particular module, start the entry with ``- [module name] -`` and include a link to the related issue if one exists. Here are some examples:
|
|
|
|
.. code-block:: yaml
|
|
|
|
bugfixes:
|
|
- win_updates - fixed issue where running win_updates on async fails without any error
|
|
|
|
.. code-block:: yaml
|
|
|
|
minor_changes:
|
|
- lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443)
|
|
|
|
Commit the changelog fragment and include it with the pull request.
|
|
|
|
|
|
|
|
Release candidates
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Before a new release or version of Ansible can be done, it will typically go
|
|
through a release candidate process.
|
|
|
|
This provides the Ansible community the opportunity to test Ansible and report
|
|
bugs or issues they might come across.
|
|
|
|
Ansible tags the first release candidate (``RC1``) which is usually scheduled
|
|
to last five business days. The final release is done if no major bugs or
|
|
issues are identified during this period.
|
|
|
|
If there are major problems with the first candidate, a second candidate will
|
|
be tagged (``RC2``) once the necessary fixes have landed.
|
|
This second candidate lasts for a shorter duration than the first.
|
|
If no problems have been reported after two business days, the final release is
|
|
done.
|
|
|
|
More release candidates can be tagged as required, so long as there are
|
|
bugs that the Ansible core maintainers consider should be fixed before the
|
|
final release.
|
|
|
|
.. _release_freezing:
|
|
|
|
Feature freeze
|
|
~~~~~~~~~~~~~~
|
|
|
|
While there is a pending release candidate, the focus of core developers and
|
|
maintainers will on fixes towards the release candidate.
|
|
|
|
Merging new features or fixes that are not related to the release candidate may
|
|
be delayed in order to allow the new release to be shipped as soon as possible.
|
|
|
|
|
|
Deprecation Cycle
|
|
`````````````````
|
|
|
|
Sometimes we need to remove a feature, normally in favor of a reimplementation that we hope does a better job.
|
|
To do this we have a deprecation cycle. First we mark a feature as 'deprecated'. This is normally accompanied with warnings
|
|
to the user as to why we deprecated it, what alternatives they should switch to and when (which version) we are scheduled
|
|
to remove the feature permanently.
|
|
|
|
The cycle is normally across 4 feature releases (2.x.y, where the x marks a feature release and the y a bugfix release),
|
|
so the feature is normally removed in the 4th release after we announce the deprecation.
|
|
For example, something deprecated in 2.5 will be removed in 2.9, assuming we don't jump to 3.x before that point.
|
|
The tracking is tied to the number of releases, not the release numbering.
|
|
|
|
For modules/plugins, we keep the documentation after the removal for users of older versions.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`community_committer_guidelines`
|
|
Guidelines for Ansible core contributors and maintainers
|
|
:ref:`testing_strategies`
|
|
Testing strategies
|
|
:ref:`ansible_community_guide`
|
|
Community information and contributing
|
|
`Ansible release tarballs <https://releases.ansible.com/ansible/>`_
|
|
Ansible release tarballs
|
|
`Development Mailing List <https://groups.google.com/group/ansible-devel>`_
|
|
Mailing list for development topics
|
|
`irc.freenode.net <http://irc.freenode.net>`_
|
|
#ansible IRC chat channel
|