From 097a1a50c87c7616eae78ed47930cbdc0eca1b92 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 1/11] Initial Ansible Collection guidelines --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 6281361..a0146e8 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -39,6 +39,7 @@ * Programming Languages ** xref:Ada.adoc[Ada] +** xref:Ansible_collections.adoc[Ansible Collections] ** xref:C_and_C++.adoc[C and {cpp}] ** xref:D.adoc[D] ** xref:Fortran.adoc[Fortran] diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc new file mode 100644 index 0000000..b858e2a --- /dev/null +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -0,0 +1,254 @@ += Ansible Collection Packaging Guidelines +:last-reviewed: 2022-08-18 +:toc: + +== Forward + +Ansible collections are packaged units of Ansible content, +including modules and other types of plugins. +Most Ansible Plugins are written in Python or Powershell. + +Some collections are also included in Ansible Community's `+ansible+` +collection bundle, which is packaged in Fedora. +This package depends on `+ansible-core+`, which contains the core engine and +CLI programs (e.g. `+ansible+`, `+ansible-playbook+`). +The `+ansible+` package has a different release cycle than individual collections, +and it may contain older versions of the individual components. +`+ansible+` installs collections in a different namespace and is parallel +installable with individual collections. +The Ansible engine searches for collections in the standalone collections +directory first. + +See https://fedoraproject.org/wiki/Changes/Ansible5[Changes/Ansible5] +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 +`+ansible-collection-community-general+`. + +Currently, all collection specfiles must have the following boilerplate: + +[source,RPMSpec] +---- +%global collection_namespace NAMESPACE +%global collection_name NAME +---- + +This is required for packaging macros to work properly, but this may be changed +in the future. + +== Collection Source + +Collection source code MUST be downloaded from the collection's respective +Git forge/other SCM repository. +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. + +Collection packages SHOULD use the `+%ansible_collection_url+` macro +as the package's `+URL:+` field. +This points to the collection's homepage on Ansible Galaxy. + + +== Dependencies + +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. + +The dependency generator will generate the appropriate dependency on the Ansible engine. +This ensures compatibility with Fedora 35 +which contains the classic `+ansible+` 2.9 package (instead of the collections bundle) +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. + +The dependency generator also handles inter-collection dependencies. + +== Build and Installation + +To build the collection artifact, +packages MUST use `+%ansible_collection_build+` in `+%build+`. +`+%ansible_collection_install+` MUST be used in `+%install+` to install the +artifact. + +The `+%ansible_collection_files+` macro MUST be used in `%files` to refer to +the collection. +Note that this is not a macro that is passed to `+%files -f+`. +It needs to be on its own line under `+%files+`. + +== Unit Tests + +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. +In order to run unit tests, collections MUST `+BuildRequire+` +`+ansible-packaging+`, which pulls in the necessary dependencies. +Collections may have other testing dependencies, +which are usually specified in `+tests/unit/requirements.txt+`. +The `+%ansible_test_unit+` macro MUST be used to run tests. + +[NOTE] +.EPEL Compatibility +==== +It is currently impossible to run unit tests on EPEL 8 and 9. + +ansible-core in RHEL 8.6 is built against python38. In c8s and the next RHEL +8 minor release, it will be built against python39. The testing dependencies +are not yet packaged for either Python version in EPEL 8. + +ansible-test in RHEL 9.0 still needs python3-mock, but this +requirement has been removed in CentOS 9 Stream. + +The rest of these guidelines are applicable to EPEL 8 and 9, +and `+ansible-packaging+` itself is available there. +==== + +== Unnecessary Files + +By default, collections ship with all of the files in the repository root, +unless they are manually excluded. +Therefore, many collections contain development files that are unwanted by users. + +Packagers SHOULD exclude these files, which SHOULD be done by patching the +collection's `+galaxy.yml+` to add these files to the `+build_ignore+` +configuration. +These files SHOULD NOT be removed with `+rm+`. +See the https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html#collection-galaxy-metadata-structure[Ansible documentation] +for more information on the `+galaxy.yml+` syntax. + +Common development files include: + +* The `+tests+` directory containing unit and integration tests +* SCM configuration such as `+.gitignore+` and `+.keep+` files +* The `+.azure-pipelines+` and `+.github+` directories that contain CI configuration + +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. + +== Shebangs + +Ansible plugins are not executable. However, many of them have `+#!/usr/bin/python+` +shebangs for legacy reasons. +These shebangs MUST be removed for the following reasons: + +1. Non-executable files shouldn't have shebangs +2. Keeping the shebangs results in an unnecessary dependency +on `+python-unversioned-command+`. + +`+%py3_shebang_fix+` MUST NOT be used, as it will break compatibility +with certain Ansible target nodes. +It won't fix the non-executable file issue, either. + +Shebangs can be removed with: + +[source,bash] +---- +find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + +---- + + +== Documentation and License Files + +License files and documentation for collections are installed to the +collection's directory in `+/usr/share/ansible+`, by default. +Packagers MAY choose to either +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. + +Note that some multi-licensed collections store licenses in a `+LICENSES+` +directory. This whole directory MUST be marked with `+%license+`. + +Refer to the xref:legal::index.adoc[Legal docs] for the rules about +allowed licenses and determining the `+License:+` field. + + +== Example Specfile + +[source,RPMSpec] +---- +# Only run tests where the dependencies are available +%if %{defined fedora} +%bcond_without tests +%else +%bcond_with tests +%endif + +%global collection_namespace community +%global collection_name rabbitmq + +Name: ansible-collection-%{collection_namespace}-%{collection_name} +Version: 1.2.2 +Release: 1%{?dist} +Summary: RabbitMQ collection for Ansible + +# plugins/module_utils/_version.py: Python Software Foundation License version 2 +License: GPL-3.0-or-later and PSF-2.0 +URL: %{ansible_collection_url} +Source0: https://github.com/ansible-collections/community.rabbitmq/archive/%{version}/%{name}-%{version}.tar.gz + +BuildRequires: ansible-packaging +%if %{with tests} +BuildRequires: ansible-packaging-tests +# Collection specific test dependency +BuildRequires: glibc-all-langpacks +%endif + +BuildArch: noarch + +%description +%{summary}. + + +%prep +%autosetup -n community.rabbitmq-%{version} +find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + +cat >> galaxy.yml << EOF +build_ignore: + # Remove unnecessary development files from the built package. + - tests + - .azure-pipelines + - .gitignore + # Licenses and docs are installed with %%doc and %%license + - PSF-license.txt + - COPYING + - README.md + - CHANGELOG.rst +EOF + + +%build +%ansible_collection_build + + +%install +%ansible_collection_install + + +%if %{with tests} +%check +%ansible_test_unit +%endif + + +%files +%license COPYING PSF-license.txt +%doc README.md CHANGELOG.rst +%{ansible_collection_files} + +%changelog +---- From 43f3f9c6e2e90bffbd7a85634a8a719f5cc9fe6c Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 2/11] Explicitly state that all collections can be packaged --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index b858e2a..4f236d5 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -10,7 +10,10 @@ Most Ansible Plugins are written in Python or Powershell. Some collections are also included in Ansible Community's `+ansible+` collection bundle, which is packaged in Fedora. -This package depends on `+ansible-core+`, which contains the core engine and +All collections, whether or not they are included in the `+ansible+` package, +MAY be packaged in Fedora. + +`+ansible+` depends on `+ansible-core+`, which contains the core engine and CLI programs (e.g. `+ansible+`, `+ansible-playbook+`). The `+ansible+` package has a different release cycle than individual collections, and it may contain older versions of the individual components. From 53b39a90f7512a4a1a205a8c97b8fbd8603e7c61 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 3/11] ansible example: Use patch file to edit metadata We should advise packagers to use actual patch files, not hacky sed'ing. --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 4f236d5..c88c10c 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -203,6 +203,9 @@ Summary: RabbitMQ collection for Ansible License: GPL-3.0-or-later and PSF-2.0 URL: %{ansible_collection_url} Source0: https://github.com/ansible-collections/community.rabbitmq/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 BuildRequires: ansible-packaging %if %{with tests} @@ -218,7 +221,7 @@ BuildArch: noarch %prep -%autosetup -n community.rabbitmq-%{version} +%autosetup -n community.rabbitmq-%{version} -p1 find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + cat >> galaxy.yml << EOF build_ignore: @@ -255,3 +258,27 @@ EOF %changelog ---- + +build_ignore.patch: + +[source, patch] +---- +diff --git a/galaxy.yml b/galaxy.yml +index 0b37162..acd029a 100644 +--- a/galaxy.yml ++++ b/galaxy.yml +@@ -13,3 +13,13 @@ repository: https://github.com/ansible-collections/community.rabbitmq + documentation: https://docs.ansible.com/ansible/latest/collections/community/rabbitmq/ + homepage: https://github.com/ansible-collections/community.rabbitmq + issues: https://github.com/ansible-collections/community.rabbitmq/issues ++build_ignore: ++ # Remove unnecessary development files from the built package. ++ - tests ++ - .azure-pipelines ++ - .gitignore ++ # Licenses and docs are installed with %%doc and %%license ++ - PSF-license.txt ++ - COPYING ++ - README.md ++ - CHANGELOG.rst +---- From 459deea93c338697c1de1158cc5bb8a820253acd Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 4/11] ansible: Expand Dependencies guidelines This expands the Dependencies section to discuss runtime collection dependencies. --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index c88c10c..e2f1bfb 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -60,12 +60,16 @@ This points to the collection's homepage on Ansible Galaxy. == Dependencies +=== Buildtime + 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. +=== Runtime + The dependency generator will generate the appropriate dependency on the Ansible engine. This ensures compatibility with Fedora 35 which contains the classic `+ansible+` 2.9 package (instead of the collections bundle) @@ -77,6 +81,37 @@ in which case the appropriate constraints should be used. The dependency generator also handles inter-collection dependencies. +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. +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. +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. +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. +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 +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. + + == Build and Installation To build the collection artifact, From f7283e0398bb1e84e739d4abc8b040984b3ac965 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 5/11] ansible: Remove section about boilerplate --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index e2f1bfb..a3c180c 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -31,16 +31,6 @@ Collection packages MUST be named `+ansible-collection-NAMESPACE-NAME+`. For example, the `+community.general+` collection is named `+ansible-collection-community-general+`. -Currently, all collection specfiles must have the following boilerplate: - -[source,RPMSpec] ----- -%global collection_namespace NAMESPACE -%global collection_name NAME ----- - -This is required for packaging macros to work properly, but this may be changed -in the future. == Collection Source From c1ee7274ffa621c5502c7520b28645d7ca15bd67 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 6/11] ansible: Document %ansible_collection_filelist --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index a3c180c..d4b5a48 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -109,10 +109,9 @@ packages MUST use `+%ansible_collection_build+` in `+%build+`. `+%ansible_collection_install+` MUST be used in `+%install+` to install the artifact. -The `+%ansible_collection_files+` macro MUST be used in `%files` to refer to +Packagers SHOULD use `+%files -f %{ansible_collection_filelist}+` to install the collection. -Note that this is not a macro that is passed to `+%files -f+`. -It needs to be on its own line under `+%files+`. +The `+%{ansible_collection_filelist}+` is populated by `+%ansible_collection_install+`. == Unit Tests From 6eaa5b5f6107306a53bff010d666f58ecd45cb47 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 7/11] ansible: Update example specfile - Stop using "legacy" macros - Fix patching mistake --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index d4b5a48..d2baaf0 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -215,18 +215,16 @@ allowed licenses and determining the `+License:+` field. %bcond_with tests %endif -%global collection_namespace community -%global collection_name rabbitmq - -Name: ansible-collection-%{collection_namespace}-%{collection_name} +Name: ansible-collection-community-rabbitmq Version: 1.2.2 Release: 1%{?dist} Summary: RabbitMQ collection for Ansible # plugins/module_utils/_version.py: Python Software Foundation License version 2 License: GPL-3.0-or-later and PSF-2.0 -URL: %{ansible_collection_url} -Source0: https://github.com/ansible-collections/community.rabbitmq/archive/%{version}/%{name}-%{version}.tar.gz +URL: %{ansible_collection_url community rabbitmq} +%global forgeurl https://github.com/ansible-collections/community.rabbitmq +Source0: %{fogeurl}/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 @@ -247,18 +245,6 @@ BuildArch: noarch %prep %autosetup -n community.rabbitmq-%{version} -p1 find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + -cat >> galaxy.yml << EOF -build_ignore: - # Remove unnecessary development files from the built package. - - tests - - .azure-pipelines - - .gitignore - # Licenses and docs are installed with %%doc and %%license - - PSF-license.txt - - COPYING - - README.md - - CHANGELOG.rst -EOF %build @@ -275,10 +261,9 @@ EOF %endif -%files +%files -f %{ansible_collection_filelist} %license COPYING PSF-license.txt %doc README.md CHANGELOG.rst -%{ansible_collection_files} %changelog ---- From 9bc48f372e43111bd1f12ec2e232acb7a808f7b5 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 8/11] ansible: Add new Macro breakdown section --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index d2baaf0..f07b558 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -291,3 +291,153 @@ index 0b37162..acd029a 100644 + - README.md + - CHANGELOG.rst ---- + + +== Macro Breakdown + +Here is a short breakdown of exactly what each macro included in +`+ansible-packaging+` does. + + +[#ansible_collection_url] +===== `+%ansible_collection_url+` + +*Usage:* + +[source,RPMSpec] +---- +URL: %{ansible_collection_url NAMESPACE NAME} +---- + +This macro points to a collection's Ansible Galaxy page. +It is intended to be used for the `+URL:+` tag in the specfile preamble. +It takes the collection namespace and collection name as arguments. + +If no arguments are passed to this macro, it falls back to the values +of `+%{collection_namespace}+` and `+%{collection_name}+` if they are set in the specfile. +New packages SHOULD explicitly pass the namespace and name as arguments. +The fallback may be removed in the future. +See the link:#legacy_macros[Legacy Macros] section for more information. + + +[#ansible_collection_build] + +===== `+%ansible_collection_build+` + +*Usage:* + +[source,RPMSpec] +---- +%build +%ansible_collection_build +---- + +This macro simply runs `+ansible-galaxy collection build+`. + + +[#ansible_collection_install] +===== `+%ansible_collection_install+` + +*Usage:* + +[source,RPMSpec] +---- +%install +%ansible_collection_install +---- + +This macro pulls out the collection namespace, name, and version from `+galaxy.yml+` +and then uses it to run `+ansible-galaxy collection install+`. +After that, it writes out `+%{ansible_collection_filelist}` based on the +metadata it previously extracted + + +[#ansible_test_unit] +===== `+%ansible_test_unit+` + +*Usage:* + +[source,RPMSpec] +---- +%check +%ansible_test_unit +---- +This macro parses galaxy.yml to determine the collection namespace and name +that's needed to create the directory structure that ansible-test expects. +After creating a temporary build directory with the needed structure, the +script runs ansible-test units with the provided arguments. + + +[#ansible_collection_filelist] +===== `+%{ansible_collection_filelist}+` + +*Usage:* + +[source,RPMSpec] +---- +%files -f %{ansible_collection_filelist} +%doc ... +%license ... +---- + +This macro points a file list that's written out by `+%ansible_collection_install+`. +Currently, it only contains a single entry to own the collection's entire +directory in `+%{ansible_collections_dir}+` + + +[#ansible_collections_dir] + +This macro expands to `+%{_datadir}/ansible/collections/ansible_collections+`. +It is used internally by the other macros. +Packagers are expected to use `+%ansible_collection_install+` and +`+%ansible_collection_filelist+` instead of directly referencing this directory. + +[#legacy_macros] +=== Legacy macros + +[#collection_namespace] +===== `+%collection_namepsace+` +*Usage:* + +[source,RPMSpec] +---- +%global collection_namespace NAMESPACE +---- + +The ansible-packaging macros previously required +packagers to manually set `+%collection_namespace+` in specfiles. +Now, the macros extract the collection namespace from the `galaxy.yml`. + + +[#collection_name] +===== `+%collection_name+` + +*Usage:* + +[source,RPMSpec] +---- +%global collection_name NAME +---- + +The ansible-packaging macros previously required +packagers to manually set `+%collection_namespace+` in specfiles. +Now, the macros extract the collection namespace from the `galaxy.yml`. + + +[#ansible_collection_files] +===== `+%{ansible_collection_files}+` + +*Usage:* + +[source,RPMSpec] +---- +%files +%doc ... +%license ... +%{ansible_collection_files} +---- + +New specfiles should use `+%files -f %{ansible_collection_filelist}+` instead +of this macro. +`+%{ansible_collection_files}+` requires setting +`+%collection_namespace+` and `+%collection_name+`. From 8d2db8a73479b14b7b8556b0bafeb3b499956951 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 9/11] ansible: Clarify %ansible_collection_url guideline --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index f07b558..fa984ec 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -43,8 +43,8 @@ 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. -Collection packages SHOULD use the `+%ansible_collection_url+` macro -as the package's `+URL:+` field. +Collection packages SHOULD use `+%{ansible_collection_url NAMESPACE NAME}+` +as the package's `+URL:+`. This points to the collection's homepage on Ansible Galaxy. From 0b0931056192c3b38182d9909184a9e1ab62a57c Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 10/11] 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:* From dce79eec9763aed66346ddafcd079baca4adc4be Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 11/11] Move Ansible to Other Domain-specific Guidelines Ansible collections are not a programming language. --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index a0146e8..2e11852 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -39,7 +39,6 @@ * Programming Languages ** xref:Ada.adoc[Ada] -** xref:Ansible_collections.adoc[Ansible Collections] ** xref:C_and_C++.adoc[C and {cpp}] ** xref:D.adoc[D] ** xref:Fortran.adoc[Fortran] @@ -66,6 +65,7 @@ ** xref:Tcl.adoc[Tcl/Tk extensions] * Other Domain-specific Guidelines +** xref:Ansible_collections.adoc[Ansible Collections] ** xref:BLAS_LAPACK.adoc[BLAS/LAPACK] ** xref:CronFiles.adoc[CronFiles] ** xref:Drupal7.adoc[Drupal7]