Backport release_and_maintenance.rst (#39755)

* document our deprecation (#37788)

* document our deprecation

fixes #37779

* Copy edit.

(cherry picked from commit 8b45cab3c1)

* Update docs and version definitions for the 2.4.4 and 2.5.0 releases

(cherry picked from commit 73c80862c8)

* Fix 2.5 changelog link

(cherry picked from commit 4165bb308b)

docs/docsite/rst/reference_appendices/release_and_maintenance.rst

@@ -40,9 +40,10 @@ Release status
 ===============   ==========================   =================================================
 Ansible Release   Latest Version               Status
 ===============   ==========================   =================================================
-devel             `2.5`_ (unreleased, trunk)   In development
-2.4               `2.4.3`_ (2018-01-31)        Supported (security **and** general bug fixes)
-2.3               `2.3.3`_ (2017-12-20)        Supported (security **and** critical bug fixes)
+devel             `2.6` (unreleased, trunk)    In development
+2.5               `2.5.0`_ (2018-03-23)        Supported (security **and** general bugfixes)
+2.4               `2.4.4`_ (2018-01-31)        Supported (security **and** critical bug fixes)
+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)
@@ -54,8 +55,10 @@ devel             `2.5`_ (unreleased, trunk)   In development
     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.
 
-.. _2.5: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
-.. _2.4.3: https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md
+.. 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.5.0: https://github.com/ansible/ansible/blob/stable-2.5/changelogs/CHANGELOG-v2.5.rst
+.. _2.4.4: https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md
 .. _2.3.3: 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
@@ -131,6 +134,22 @@ 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`

packaging/release/vars/versions.yml

@@ -8,6 +8,7 @@ versions:
 - "2.4":
     code_name: "Dancing Days"
     releases:
+    - "4": "04-04-2018"
     - "3": "01-31.2018"
     - "2": "11-29-2017"
     - "1": "10-25-2017"