From 0b0931056192c3b38182d9909184a9e1ab62a57c Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: ansible: Fix wording and typos --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index fa984ec..5053721 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -1,5 +1,5 @@ = Ansible Collection Packaging Guidelines -:last-reviewed: 2022-08-18 +:last-reviewed: 2022-09-25 :toc: == Forward @@ -28,7 +28,7 @@ for more information about the split between `+ansible+` and `+ansible-core+`. == Naming Collection packages MUST be named `+ansible-collection-NAMESPACE-NAME+`. -For example, the `+community.general+` collection is named +For example, the `+community.general+` collection package is named `+ansible-collection-community-general+`. @@ -40,8 +40,8 @@ While the tarballs published to Ansible Galaxy contain all of the collection's Python/Powershell source code as well as some development files, they do not include the `+galaxy.yml+` build configuration and development files (e.g. unit tests) that the author may choose to remove. -Note that the community Collection Guidelines require collections to tag releases -in a public SCM repository. +Note that the Ansible Community collection requirements mandate that +collections tag releases in a public SCM repository. Collection packages SHOULD use `+%{ansible_collection_url NAMESPACE NAME}+` as the package's `+URL:+`. @@ -52,11 +52,11 @@ This points to the collection's homepage on Ansible Galaxy. === Buildtime -Collections MUST have `+BuildRequires: +ansible-packaging+`. +Collections MUST have `+BuildRequires: ansible-packaging+`. `+ansible-packaging+` provides macros and a dependency generator for packaging Ansible Collections. It also pulls in `+ansible-core+`, -so `+BuildRequires: ansible-core+` shouldn't be added manually. +so `+BuildRequires: ansible-core+` SHOULD NOT be added manually. === Runtime @@ -67,20 +67,23 @@ and `+ansible-core+`. Both versions of the Ansible engine support collections, but they are not parallel installable. Packages MUST NOT manually `+Require+` `+ansible-core+` or `+ansible+`, unless they are known to require a specific version, -in which case the appropriate constraints should be used. +in which case the appropriate version constraints should be used. The dependency generator also handles inter-collection dependencies. +==== External dependencies of plugins + Ansible collections may contain various plugins that have various external dependencies. The Ansible dev guide https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code[mandates] -that plugins fail cleanly if these dependencies. +that plugins fail cleanly if these dependencies are not installed. +Many times, external dependencies are only needed for a small subset of the +collection which may or may not be widely used. Therefore, collection packages SHOULD weakly depend on these external libraries, i.e. use Recommends instead of Requires. -Module dependencies are only needed on the target node, -not the controller node. +Module dependencies are only needed on the target node not the controller node. Therefore, collection packages SHOULD NOT depend on these dependencies at all, weakly or strongly. Users are responsible for installing these dependencies on the target host. @@ -88,18 +91,18 @@ Modules that are intended to be used with `+delegate_to: localhost+` are an exception to this rule. The situation is a bit different for controller plugins, such as -filter plugins, lookup plugins, connection plugins, and inventory plugins. -Collections MAY add `+Recommends+` for these dependencies. +filter plugins, lookup plugins, connection plugins, or inventory plugins. +Collections MAY add `+Recommends+` for dependencies of controller plugins. However, packagers should use discretion when adding any type of dependency and only do so when it is required for the central functionality of the collection. For instance, it makes sense for `+ansible-collection-community-docker+` -to Recommend python3-docker. -On the other hand, it wouldn't make sense for the larger, more general +to Recommend `+python3-docker+`, +but it doesn't make sense for the larger, more general ansible-collection-community-general collection to Recommend `+python3-redis+` for the `+redis+` lookup plugin. -This guidelines seeks to prevent ballooning collection packages. -`+ansible-core+` and `+ansible+` follows this same principal. +This guideline seeks to prevent ballooning collection packages. +`+ansible-core+` and `+ansible+` follow this same principal. == Build and Installation @@ -117,11 +120,12 @@ The `+%{ansible_collection_filelist}+` is populated by `+%ansible_collection_ins As per xref:index.adoc#_test_suites[the general Fedora Packaging Guidelines], collection packages SHOULD run upstream unit tests in `+%check+` if practical. -Integration tests are impossible to run in the rpm environment. +Integration tests are impossible to run in the RPM build environment. In order to run unit tests, collections MUST `+BuildRequire+` -`+ansible-packaging+`, which pulls in the necessary dependencies. -Collections may have other testing dependencies, +`+ansible-packaging-tests+`, which pulls in the necessary dependencies. +Some collections have other testing dependencies, which are usually specified in `+tests/unit/requirements.txt+`. +These have to be added manually. The `+%ansible_test_unit+` macro MUST be used to run tests. [NOTE] @@ -161,8 +165,7 @@ Common development files include: These files often have to be removed downstream, as there are some unresolved issues with pushing these changes to upstream community collections. These -issues are mostly related to the way Ansible Community compiles the `+ansible+` -bundle and are irrelevant in the Fedora context. +issues are irrelevant in the Fedora context. == Shebangs @@ -195,7 +198,7 @@ mark the license and documentation files in this directory with `+%license+` and `+%doc+` or to add the correct paths to `+build_ignore+` in `+galaxy.yml+` and install them into the standard directories. -Packages should avoid duplicating these files in both places. +Avoid duplicating these files in both places. Note that some multi-licensed collections store licenses in a `+LICENSES+` directory. This whole directory MUST be marked with `+%license+`. @@ -224,7 +227,7 @@ Summary: RabbitMQ collection for Ansible License: GPL-3.0-or-later and PSF-2.0 URL: %{ansible_collection_url community rabbitmq} %global forgeurl https://github.com/ansible-collections/community.rabbitmq -Source0: %{fogeurl}/archive/%{version}/%{name}-%{version}.tar.gz +Source0: %{forgeurl}/archive/%{version}/%{name}-%{version}.tar.gz # Patch galaxy.yml to exclude unnecessary files from the built collection. # This is a downstream only patch. Patch0: build_ignore.patch @@ -396,7 +399,7 @@ Packagers are expected to use `+%ansible_collection_install+` and === Legacy macros [#collection_namespace] -===== `+%collection_namepsace+` +===== `+%{collection_namepsace}+` *Usage:* [source,RPMSpec] @@ -410,7 +413,7 @@ Now, the macros extract the collection namespace from the `galaxy.yml`. [#collection_name] -===== `+%collection_name+` +===== `+%{collection_name}+` *Usage:*