From e2d874c744698d97b603262a2f8a4d4d44c76782 Mon Sep 17 00:00:00 2001 From: David Moreau-Simard Date: Fri, 21 Jul 2017 16:05:02 -0400 Subject: [PATCH] Improve release and development cycle documentation This commit: - Adds a table highlighting the status of each version and provides a link to each major release's changelog - Re-inforces how stable versions are maintained and for how long - Moves this documentation out of the developer tree (this is interesting for users too!) while keeping a link there. --- .../rst/dev_guide/developing_releases.rst | 57 -------- docs/docsite/rst/dev_guide/index.rst | 2 +- docs/docsite/rst/index.rst | 2 +- docs/docsite/rst/release_and_maintenance.rst | 137 ++++++++++++++++++ 4 files changed, 139 insertions(+), 59 deletions(-) delete mode 100644 docs/docsite/rst/dev_guide/developing_releases.rst create mode 100644 docs/docsite/rst/release_and_maintenance.rst diff --git a/docs/docsite/rst/dev_guide/developing_releases.rst b/docs/docsite/rst/dev_guide/developing_releases.rst deleted file mode 100644 index 4903608248..0000000000 --- a/docs/docsite/rst/dev_guide/developing_releases.rst +++ /dev/null @@ -1,57 +0,0 @@ -Releases -======== - -.. contents:: Topics - :local: - -.. _support_life: - -Support for older releases -`````````````````````````` - -Ansible supports the two most recent major, stable releases. Security- and bug-related fixes may be implemented in older versions, but this -support is not guaranteed. - -If you are on a release older than the last two major, stable releases, please see our `Porting Guide `_. - -.. _schedule: - -Release schedule -```````````````` -Ansible is on a 'flexible' 4 month release schedule. Sometimes the release cycle can be extended if there is a major change that requires more time (for example, a core rewrite). -Recently the main Ansible repo `merged `_ the separated ansible-modules-core and ansible-modules-extras repos, as such modules get released at the same time as the main Ansible repo. - -The major features and bugs fixed in a release should be reflected in the `CHANGELOG.md `_. Minor features and bug fixes will be shown in the commit history. For example, `issue #19057 `_ is reflected only in the commit history. -When a fix orfeature gets added to the `devel` branch it will be part of the next release. Some bugfixes can be backported to previous releases and will be part of a minor point release if such a release is deemed necessary. - -Sometimes a release candidate can be extended by a few days if a bug fix makes a change that can have far-reaching consequences, so users have enough time to find any new issues that may stem from this. - -.. _methods: - -Release methods -```````````````` - -Ansible normally goes through a 'release candidate', issuing an RC1 for a release. If no major bugs are discovered in the release candidate after 5 business days, we'll get a final release. Otherwise, fixes will be applied and an RC2 will be provided for testing. If no bugs are discovered in RC2 after 2 days, the final release will be made, iterating this last step and incrementing the candidate number as we find major bugs. - - -.. _freezing: - -Release feature freeze -`````````````````````` - -During the release candidate process, the focus will be on bugfixes that affect the RC, new features will be delayed while we try to produce a final version. Some bugfixes that are minor or don't affect the RC will also be postponed until after the release is finalized. - -.. seealso:: - - :doc:`developing_api` - Python API to Playbooks and Ad Hoc Task Execution - :doc:`developing_modules` - How to develop modules - :doc:`developing_plugins` - How to develop plugins - `Ansible Tower `_ - REST API endpoint and GUI for Ansible, syncs with dynamic inventory - `Development Mailing List `_ - Mailing list for development topics - `irc.freenode.net `_ - #ansible IRC chat channel diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index 4b24f64256..ce33692150 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -33,6 +33,6 @@ To get started, select one of the following topics. developing_rebasing testing repomerge - developing_releases + ../release_and_maintenance ../committer_guidelines ./style_guide/index diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index 997351c1d9..dc503191c6 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -42,4 +42,4 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo YAMLSyntax porting_guide_2.0 python_3_support - + release_and_maintenance diff --git a/docs/docsite/rst/release_and_maintenance.rst b/docs/docsite/rst/release_and_maintenance.rst new file mode 100644 index 0000000000..8898b1ceff --- /dev/null +++ b/docs/docsite/rst/release_and_maintenance.rst @@ -0,0 +1,137 @@ +Release and maintenance +======================= + +.. contents:: Topics + :local: + +.. _schedule: + +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 supports the two most recent major stable releases. +For more information, read about the +`development and stable version maintenance workflow`_. + +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 `porting guide`_ for tips on updating your Ansible +playbooks to run on newer versions. + +.. _porting guide: https://docs.ansible.com/ansible/porting_guide_2.0.html + +Release status +`````````````` + ++-----------------+----------------------------+----------------------------------------+ +| Ansible release | Latest version | Status | ++=================+============================+========================================+ +| devel | `2.4`_ (unreleased, trunk) | In development | ++-----------------+----------------------------+----------------------------------------+ +| 2.3 | `2.3.1`_ (2017-06-01) | Supported (bug **and** security fixes) | ++-----------------+----------------------------+----------------------------------------+ +| 2.2   | `2.2.3`_ (2017-05-09) | Supported (**only** security fixes) | ++-----------------+----------------------------+----------------------------------------+ +| 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) | ++-----------------+----------------------------+----------------------------------------+ + +.. _2.4: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md +.. _2.3.1: https://github.com/ansible/ansible/blob/stable-2.3/CHANGELOG.md +.. _2.2.3: https://github.com/ansible/ansible/blob/stable-2.2/CHANGELOG.md +.. _2.1.6: https://github.com/ansible/ansible/blob/stable-2.1/CHANGELOG.md +.. _2.0.2: https://github.com/ansible/ansible/blob/stable-2.0/CHANGELOG.md +.. _1.9.6: https://github.com/ansible/ansible/blob/stable-1.9/CHANGELOG.md + +.. _support_life: +.. _methods: + +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 while the previous major release will only receive security patches. +This work is tracked on the ``stable-`` git branches. + +The fixes that land in supported stable branches will eventually be released +as a new version when necessary. + +For more information on the changes included in each new version, you can refer +to the changelog_, available on GitHub. + +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 +.. _changelog: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md + +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. + +.. _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. + +.. seealso:: + + :doc:`committer_guidelines` + Guidelines for Ansible core contributors and maintainers + :doc:`test_strategies` + Testing strategies + :doc:`community` + Community information and contributing + `Ansible Changelog `_ + Documentation of the improvements for each version of Ansible + `Ansible release tarballs `_ + Ansible release tarballs + `Development Mailing List `_ + Mailing list for development topics + `irc.freenode.net `_ + #ansible IRC chat channel