Skip to content

Commit 6c74e0a

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

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
@@ -332,7 +332,36 @@ Dates listed indicate the start date of the maintenance cycle.
332332
.. _2.16: https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst
333333
.. _2.17: https://github.com/ansible/ansible/blob/stable-2.17/changelogs/CHANGELOG-v2.17.rst
334334

335+
.. _ansible_core_versioning:
335336

337+
``ansible-core`` versioning
338+
---------------------------
339+
340+
The ansible-core project uses a historical versioning scheme, most similar to the versioning scheme used by Python.
341+
342+
This scheme follows the formatting of ``X.Y.Z`` which is described in detail below.
343+
344+
What is the ``X`` in ``X.Y.Z``?
345+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
346+
347+
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.
348+
349+
- ``v1`` can be best described as the internal architecture revolving around ``ansible.runner.Runner`` as the "execution" engine
350+
- ``v2`` can be best described as the internal architecture revolving around the ``TaskQueueManager``, ``PlayIterator``, and the strategy as the "execution" engine
351+
352+
What is the ``Y`` in ``X.Y.Z``?
353+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
354+
355+
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.
356+
357+
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``.
358+
359+
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.
360+
361+
What is the ``Z`` in ``X.Y.Z``?
362+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
363+
364+
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`.
336365

337366
Preparing for a new release
338367
===========================

0 commit comments

Comments
 (0)