Dependency rules (#205)

* Move part on collection dependencies to own top-level section.

* Add rules on dependencies.

* Fix underlining.

* Apply suggestions from code review

Co-authored-by: Andrew Klychkov <[email protected]>

* Improve formulations.

* Improve English.

Co-authored-by: Alexei Znamensky <[email protected]>

* Improve wording.

Co-authored-by: Tabah Baridule <[email protected]>

* Update collection_requirements.rst

* Improve formulation, fix example

Co-authored-by: Sandra McCann <[email protected]>

Co-authored-by: Andrew Klychkov <[email protected]>
Co-authored-by: Alexei Znamensky <[email protected]>
Co-authored-by: Tabah Baridule <[email protected]>
Co-authored-by: Sandra McCann <[email protected]>

collection_requirements.rst

@@ -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.
@@ -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:
+
+    #. 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 depended on to be held 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 collection being depended on.
+
+* 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.foo`` is removed (in the next major release), or loosens its requirements so that newer ``community.bar 1.3.z`` releases can be included.
+
+#. ``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.
 
 Requirements for collections to be included in the Ansible Package
 ==================================================================