Skip to content

Commit 6bcda9d

Browse files
authored
ansible-core versioning scheme docs (#2666)
* ansible-core versioning scheme docs * Small rewordings
1 parent d13bc13 commit 6bcda9d

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
@@ -334,7 +334,36 @@ Dates listed indicate the start date of the maintenance cycle.
334334
.. _2.18: https://github.com/ansible/ansible/blob/stable-2.18/changelogs/CHANGELOG-v2.18.rst
335335
.. _2.19: https://github.com/ansible/ansible/blob/stable-2.19/changelogs/CHANGELOG-v2.19.rst
336336

337+
.. _ansible_core_versioning:
337338

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

339368
Preparing for a new release
340369
===========================

0 commit comments

Comments
 (0)