Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Python requirements for Ansible inclusion requirements document #281

Merged
merged 2 commits into from
Aug 31, 2023
Merged

Update Python requirements for Ansible inclusion requirements document #281

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
327240e
Update Python requirements for Ansible inclusion requirements document.
felixfontein Aug 10, 2023
47cf6b4
Avoid passive voice.
felixfontein Aug 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions docs/docsite/rst/community/collection_contributors/collection_requirements.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,34 +85,36 @@ Python requirements for a collection vary between **controller environment** and

One example scenario where the "even if" clause comes into play is when using cloud modules. These modules mostly run on the controller node but in some environments, the controller might run on one machine inside a demilitarized zone which cannot directly access the cloud machines. The user has to have the cloud modules run on a bastion host/jump server which has access to the cloud machines.

An **eligible controller Python version** for a collection is a Python version that is supported on the controller side by at least one ansible-core version that the collection supports. Similarly, an **eligible target Python version** for a collection is a Python version that is supported on the target side by at least one ansible-core version that the collection supports. The eligible controller and target Python versions can be determined from the :ref:`ansible_core_support_matrix` and from the ``requires_ansible`` value in ``meta/runtime.yml`` in the collection.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
An **eligible controller Python version** for a collection is a Python version that is supported on the controller side by at least one ansible-core version that the collection supports. Similarly, an **eligible target Python version** for a collection is a Python version that is supported on the target side by at least one ansible-core version that the collection supports. The eligible controller and target Python versions can be determined from the :ref:`ansible_core_support_matrix` and from the ``requires_ansible`` value in ``meta/runtime.yml`` in the collection.
An **eligible controller Python version** for a collection is a Python version that is supported on the controller side by at least one ansible-core version that the collection supports. Similarly, an **eligible target Python version** for a collection is a Python version that is supported on the target side by at least one ansible-core version that the collection supports. The eligible controller and target Python versions can be determined from the :ref:`ansible_core_support_matrix` and from the ``requires_ansible`` value in ``meta/runtime.yml`` in the collection.
  • can we replace the word eligible with a synonym if possible? allowed or acceptable maybe? can be easier to understand for not native speakers
  • can we add an example? something like For example, if your collection supports ansible-core version A (supports Python ...) and ansible-core version B (supports Python ...), the acceptable controller Python version is ...?. Same for target versions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, 'acceptable' could be ok, or maybe 'admissible'. I'd like to hear some more comments on this, also from native english speakers :)

About adding an example: there is already one starting directly after the diff that GitHub shows ends, in the part on documentation requirements. Is that one enough, or should we have another one here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd agree with the word acceptable than allowed

I will also like to suggest that this part of the sentence "An eligible controller Python version for a collection is a Python version that is supported on the controller side by at least one ansible-core version that the collection supports."

could be rewritten as "An acceptable controller Python version for collection is a Python version that is supported on the controller side by at least one ansible-core version that the collection supports."

Similarly, for target versions, take off the a before collection

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you sure that removing the a before collection is fine? That sounds really wrong to me.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

about the examples, if there are any, it's OK

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

acceptable and/or desirable sounds like good options here.

I agree, removing a before collection does not sound right.

"An acceptable controller Python version for a collection is the Python version(s) that is supported on the controller side by at least one ansible-core version that the collection supports."

the Python version(s) does this change sound more accurate?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll throw another one into the mix and say suitable because it has less negative/weird connotation than acceptable and desirable. Also eligible doesn't quite fit imo. Something can be eligible without really being suitable.


.. _coll_controller_req:

Controller environment
~~~~~~~~~~~~~~~~~~~~~~

In the controller environment, collections MUST support Python 2 (version 2.7) and Python 3 (Version 3.6 and higher), unless required libraries do not support these versions. Collections SHOULD also support Python v3.5 if all required libraries support this version.
Collections MUST support all eligible controller Python versions in the controller environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee <steering_responsibilities>` can grant other exceptions on a case-by-case basis.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Collections MUST support all eligible controller Python versions in the controller environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee <steering_responsibilities>` can grant other exceptions on a case-by-case basis.
Collections MUST support all eligible controller Python versions in the controller environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee <steering_responsibilities>` can grant other exceptions on a case-by-case basis.

i would replace eligible also here (see the comment above) and everywhere with a synonym.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this all be simplified to:
Collections MUST support all Python versions listed in refansible_core_support_matrix for all ansible-core versions that the collection supports. The exception is if required libraries for the collection do not support these Python versions. Steering committee blablabla...

Then we avoid having to define 'eligible' python versions entirely have less for the reader to ...read and understand.
`

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's too late to make larger changes to this, since we already started voting on it - see ansible-community/community-topics#268. Right now we should stick so simple wording changes or small formulation changes that don't change meanings.

Also if we simplify it, it should be

Collections MUST support all Python versions listed in :ref:ansible_core_support_matrix in the Controller Python column for all ansible-core versions that the collection supports.

Also this needs to be repeated six times in the text (sometimes with Controller Python, sometimes with Target Python). I'm not sure that really improves readability.

Copy link
Contributor

@Andersson007 Andersson007 Aug 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's merge it as voted and then think about simplifications. I think the requirements (especially Python-related) look hard to read and understand overall (at least to me). But let's do it in a dedicated separate PR


The collection MUST document all eligible controller Python versions that are not supported in the controller environment. See :ref:`coll_python_docs_req` for details.

Other environment
~~~~~~~~~~~~~~~~~

In the other environment, collections MUST support Python 2 (version 2.7) and Python 3 (Version 3.6 and higher), unless required libraries do not support these versions. Collections SHOULD also support Python v2.6 and v3.5 if all required libraries support this version.
Collections MUST support all eligible controller Python versions in the other environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee <steering_responsibilities>` can grant other exceptions on a case-by-case basis.

.. note::
Collections SHOULD support all eligible target Python versions in the other environment.

If the collection does not support Python 2.6 and/or Python 3.5 explicitly then take the below points into consideration:
The collection MUST document all eligible target Python versions that are not supported in the other environment. See :ref:`coll_python_docs_req` for details.

- Dropping support for Python 2.6 in the other environment means that you are dropping support for RHEL6. RHEL6 ended full support in November, 2020, but some users are still using RHEL6 under extended support contracts (ELS) until 2024. ELS is not full support; not all CVEs of the python-2.6 interpreter are fixed, for instance.

- Dropping support for Python 3.5 means that Python 2.7 has to be installed on Ubuntu Xenial (16.04) and that you have to support Python 2.7.
.. note::

Also, note that dropping support for a Python version for an existing module/plugin is a breaking change, and thus requires a major release. A collection MUST announce dropping support for Python versions in their changelog, if possible in advance (for example, in previous versions before support is dropped).
Note that dropping support for a Python version for an existing module/plugin is a breaking change, and thus requires a major release. A collection MUST announce dropping support for Python versions in their changelog, if possible in advance (for example, in previous versions before support is dropped).

.. _coll_python_docs_req:

Python documentation requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* If everything in your collection supports the same Python versions as the collection-supported versions of ansible-core, you do not need to document Python versions.
* If everything in your collection supports all eligible controller/target Python versions, you do not need to document supported Python versions.
* If your collection does not support those Python versions, you MUST document which versions it supports in the README.
* If most of your collection supports the same Python versions as ansible-core, but some modules and plugins do not, you MUST include the supported Python versions in the documentation for those modules and plugins.

Expand Down
2 changes: 2 additions & 0 deletions docs/docsite/rst/reference_appendices/release_and_maintenance.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,8 @@ Starting with ``ansible-core`` version 2.16, each release includes target node s

Support for Python 2.7 is included in ``ansible-core`` version 2.16 and earlier.

.. _ansible_core_support_matrix:

``ansible-core`` support matrix
-------------------------------

Expand Down