Skip to content

Commit d98fab2

Browse files
ansible-core versioning scheme docs (#2666) (#2696)
* ansible-core versioning scheme docs * Small rewordings (cherry picked from commit 6bcda9d) Co-authored-by: Matt Martz <[email protected]>
1 parent 94c0019 commit d98fab2

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

docs/docsite/rst/reference_appendices/release_and_maintenance.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,36 @@ Dates listed indicate the start date of the maintenance cycle.
331331
.. _2.15: https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst
332332
.. _2.16: https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst
333333

334+
.. _ansible_core_versioning:
334335

336+
``ansible-core`` versioning
337+
---------------------------
338+
339+
The ansible-core project uses a historical versioning scheme, most similar to the versioning scheme used by Python.
340+
341+
This scheme follows the formatting of ``X.Y.Z`` which is described in detail below.
342+
343+
What is the ``X`` in ``X.Y.Z``?
344+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345+
346+
The ``X`` represents the internal architecture of ``ansible-core``. The ``X`` here does not imply any form of compatibility, nor anything about the scope of the changes.
347+
348+
- ``v1`` can be best described as the internal architecture revolving around ``ansible.runner.Runner`` as the "execution" engine
349+
- ``v2`` can be best described as the internal architecture revolving around the ``TaskQueueManager``, ``PlayIterator``, and the strategy as the "execution" engine
350+
351+
What is the ``Y`` in ``X.Y.Z``?
352+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
353+
354+
Approximately every 6 months, in May and November ansible-core releases a new *Major* release. This is denoted by the ``Y`` in the ``X.Y.Z`` version scheme.
355+
356+
Although the ``Y`` denotes the Major version, it is not referenced independently, and instead a Major version is indicated in the format of ``X.Y``, such as ``2.16``.
357+
358+
As such, versions like ``2.9.0``, ``2.10.0``, ``2.11.0``, ``2.16.0`` and ``2.19.0`` are all major releases. ``X.Y.0`` releases do not carry any guarantee of 100% backwards compatibility with the version before it. Some may be more or less impactful based on the scope of the work for the release. Check porting guides for changes that may necessitate user intervention.
359+
360+
What is the ``Z`` in ``X.Y.Z``?
361+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362+
363+
This is the patch version. ansible-core operates on a 4 week patch schedule. The ``Z`` release of a major version will include bugfixes and security fixes as outlined in the :ref:`ansible_core_support_matrix`.
335364

336365
Preparing for a new release
337366
===========================

0 commit comments

Comments
 (0)