Skip to content
This repository has been archived by the owner on May 28, 2024. It is now read-only.

Dependency rules #205

Merged
merged 9 commits into from
Aug 3, 2022
52 changes: 42 additions & 10 deletions collection_requirements.rst
Original file line number Diff line number Diff line change
Expand Up @@ -115,16 +115,7 @@ galaxy.yml
----------

* The ``tags`` field MUST be set.
* Collection dependencies must have a lower bound on the version which is at least 1.0.0.

* This means that all collection dependencies have to specify lower bounds on the versions, and these lower bounds should be stable releases, and not versions of the form 0.x.y.
* When creating new collections where collection dependencies are also under development, you need to watch out since Galaxy checks whether dependencies exist in the required versions:

#. Assume that ``foo.bar`` depends on ``foo.baz``.
#. First release ``foo.baz`` as 1.0.0.
#. Then modify ``foo.bar``'s ``galaxy.yml`` to specify ``'>=1.0.0'`` for ``foo.baz``.
#. Finally release ``foo.bar`` as 1.0.0.

* Collection dependencies must meet a set of rules. See the section on `Collection Dependencies <collection_dependencies_>`_ for this.
* The ``ansible`` package MUST NOT depend on collections not shipped in the package.
* If you plan to split up your collection, the new collection MUST be approved for inclusion before the smaller collections replace the larger in Ansible.
* If you plan to add other collections as dependencies, they MUST run through the formal application process.
Expand Down Expand Up @@ -384,6 +375,47 @@ Besides all the requirements listed in the `Development conventions <https://doc
create new ``_info`` or ``_facts`` modules instead (for more information, refer to the `Developing modules guidelines <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html#creating-an-info-or-a-facts-module>`_)
* ``check_mode`` is supported in all ``*_info`` and ``*_facts`` modules (for more information, refer to the `Development conventions <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html#following-ansible-conventions>`_)

.. _collection_dependencies:

Collection Dependencies
=======================

**Notation:** if foo.bar has a dependency on baz.bam, we say that baz.bam is the collection *depended on*, and foo.bar is the *dependent collection*.

* Collection dependencies must have a lower bound on the version which is at least 1.0.0.

* This means that all collection dependencies have to specify lower bounds on the versions, and these lower bounds should be stable releases, and not versions of the form 0.x.y.
* When creating new collections where collection dependencies are also under development, you need to watch out since Galaxy checks whether dependencies exist in the required versions:
Copy link
Contributor

Choose a reason for hiding this comment

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

Could you please expand what you mean by under development? Would that be <= 1.0.0?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes. This is basically about two dependent collections simultaneously reaching the 1.0.0 goal while producing versions that satisfy our rules.

Copy link
Contributor

Choose a reason for hiding this comment

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

Wouldn't it make sense to bar not only the collections under dev but also the ones that depend on collections under dev? I mean, if the purpose of the rule is reliability/stability, I suppose that would go a long way.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We only accept collections that released version 1.0.0 for inclusion anyway. Also note that this part of this PR has been in the rules for years, it only moved to a new place in this document.

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm concerned with the use of the word "under development", what if that could be changed to "under developed"

Let's assume this - * When creating new collections where collection dependencies are also under developed,
What do you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm not a native English speaker, but "under developed" seems to mean something completely different to me. ("in development" would be an alternative - https://english.stackexchange.com/questions/238497/which-expression-is-correct-in-development-or-under-development)

Copy link
Contributor

Choose a reason for hiding this comment

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

Oooh, interesting I just learned that now. Thanks


#. Assume that ``foo.bar`` depends on ``foo.baz``.
#. First release ``foo.baz`` as 1.0.0.
#. Then modify ``foo.bar``'s ``galaxy.yml`` to specify ``'>=1.0.0'`` for ``foo.baz``.
#. Finally release ``foo.bar`` as 1.0.0.

* The dependencies between collections included in Ansible must be valid. If a dependency is violated, the involved collections must be pinned so that all dependencies are valid again. This means that the version numbers from the previous release are kept or only partially incremented so that the resulting set of versions has no invalid dependencies.

* If a collection has a too strict dependency for a longer time, and forces another collection to be hold back, that collection will be removed from the next major Ansible release. What "longer time" means depends on when the next Ansible major release happens. If a dependent collection prevents a new major version of a collection it depends on to be included in the next major Ansible release, the dependent collection will be removed from that major release to avoid blocking the dependent collection.
felixfontein marked this conversation as resolved.
Show resolved Hide resolved

* We strongly suggest that collections also test against the ``main`` branches of their dependencies to ensure that incompatibilities with future releases of these are detected as early as possible and can be resolved in time to avoid such problems. Collections depending on other collections must understand that they bear the risk of being removed when they do not ensure compatibility with the latest releases of their dependencies.

* Collections included in Ansible must not depend on other collections except if they satisfy one of the following cases:

#. They have a loose dependency on one (or more) major versions of other collections included in Ansible. For example, ``ansible.netcommon: >=1.0.0``, or ``ansible.netcommon: >=2.0.0, <3.0.0``. In case the collection depended on releases a new major version outside of this version range that will be included in the next major Ansible release, the dependent collection will be removed from the next major Ansible release. The cut-off date for this is feature freeze.
#. They are explicitly being allowed to do so by the Steering Committee.

Examples
--------

#. ``community.foo 1.2.0`` has a dependency on ``community.bar >= 1.0.0, < 1.3.0``.

* Now ``community.bar`` creates a new release ``1.3.0``. When ``community.foo`` does not create a new release with a relaxed dependency, we have to include ``community.bar 1.2.x`` in the next Ansible release despite ``1.3.0`` being available.
* If ``community.foo`` does not relax its dependency on ``community.bar`` for some time, ``community.foo`` will be removed from the next Ansible major release.
* Unfortunately ``community.bar`` has to stay at ``1.2.x`` until either ``community.bar`` is removed (in the next major release), or loosens its requirements so that newer ``community.foo 1.y.z`` releases can be included.
felixfontein marked this conversation as resolved.
Show resolved Hide resolved

#. ``community.foonetwork`` depends on ``ansible.netcommon >= 2.0.0, <3.0.0``.

* ``ansible.netcommon 4.0.0`` is released during this major Ansible release cycle.
* ``community.foonetwork`` either releases a new version before feature freeze of the next major Ansible release that allows depending on all ``ansible.netcommon 4.x.y`` releases, or it will be removed from the next major Ansible release.
Copy link
Contributor

Choose a reason for hiding this comment

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

This should be determined automatically, and there should be some sort of a state-file holding this info between releases.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This sounds pretty complicated for something that hopefully never happens, and if it does can be handled with issues and already preparing removal from the upcoming major version (as its ansible.in already exists in a new directory).


Requirements for collections to be included in the Ansible Package
==================================================================
Expand Down