From 9bc48f372e43111bd1f12ec2e232acb7a808f7b5 Mon Sep 17 00:00:00 2001
From: Maxwell G <gotmax@e.email>
Date: Nov 12 2022 20:16:36 +0000
Subject: 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+`.