release playbook: enforce release tagging policy (#518)

* release playbook: enforce release tagging policy

- ansible >= 7.2.0 and < 9.0.0a1 -- the playbook will validate the tags
  file and *warn* but not *error* for violating collections.
- ansible >= 9.0.0a1 -- the playbook will treat violations as errors.

* tagging: ignore blank lines in ignores file

changelogs/fragments/518-enforce-release-tagging.yaml

@@ -0,0 +1,6 @@
+---
+minor_changes:
+  - release playbook - run ``antsibull-build validate-tags-file`` to ensure
+    that collections follow the Release Management section of the Collection
+    Requirements
+    (https://github.com/ansible-community/antsibull/pull/518).

roles/build-release/defaults/main.yaml

@@ -41,6 +41,24 @@ antsibull_ansible_venv: "{{ antsibull_sdist_dir }}/venv"
 # Whether or not to start from scratch with a new venv if one exists
 antsibull_venv_cleanup: true
 
+
+#####
+# These variables relate to verifying that collections properly tag their
+# releases as per the Collection Requirements.
+# None of them apply if antsibull_tags_validate is false
+#####
+# Whether to generate a tags data file and validate it
+antsibull_tags_validate: "{{ antsibull_ansible_version is
+                             _antsibull_packaging_version('7.2.0', '>=') }}"
+
+# Whether to abort on `antsibull-build validate-tags-file` errors.
+# When False, only warnings are printed.
+# This option is unconditionally enabled for `ansible >= 9.0.0a1`.
+antsibull_tags_enforce_policy: false
+
+# File containing a newline separated list of collections to ignore
+antsibull_tags_ignores_file: "{{ antsibull_data_dir }}/validate-tags-ignores"
+
 # TODO:
 # --dest-data-dir (Directory to write .build and .deps files to, as well as changelog and porting guide if applicable. Defaults to --data-dir)
 # --collection-cache (Directory of cached collection tarballs. Will be used if a collection tarball to be downloaded exists in here, and will be populated when downloading new tarballs.)

roles/build-release/meta/argument_specs.yml

@@ -85,3 +85,26 @@ argument_specs:
           - Whether or not to start from scratch with a new venv if one exists.
         type: bool
         default: true
+
+      antsibull_tags_validate:
+        description:
+          - Whether to generate a tags data file as part of the release and
+            validate it.
+          - This is enabled by default for C(ansible >= 7.2.0).
+        type: bool
+
+      antsibull_tags_enforce_policy:
+        description:
+          - Whether to abort on C(antsibull-build validate-tags-file) errors;
+            when False, only warnings are printed.
+          - This option is unconditionally enabled for C(ansible >= 9.0.0a1).
+          - This option does nothing if O(antsibull_tags_validate) is False.
+        type: bool
+
+      antsibull_tags_ignores_file:
+        description:
+          - File containing a newline separated list of collections to ignore
+            when running C(antsibull-build validate-tags-file).
+            This file will be ignored if it doesn't exist.
+        type: path
+        default: "{{ antsibull_data_dir }}/validate-tags-ignores"

roles/build-release/tasks/build.yaml

@@ -8,12 +8,15 @@
     _deps_file: "ansible-{{ antsibull_ansible_version }}.deps"
     _galaxy_file: "ansible-{{ antsibull_ansible_version }}.yaml"
     _build_file: "{{ antsibull_data_dir }}/ansible-{{ antsibull_ansible_version.split('.', 1)[0] }}.build"
-    _tags_file: "{{ '' if antsibull_ansible_version is
-                    _antsibull_packaging_version('7.2.0', '<') else
-                    '--tags-file'}}"
     _release_archive: "{{ antsibull_sdist_dir }}/ansible-{{ antsibull_ansible_version }}.tar.gz"
     _release_wheel: "{{ antsibull_sdist_dir }}/ansible-{{ antsibull_ansible_version }}-py3-none-any.whl"
 
+- name: Override antsibull_enforce_tag_policy
+  when: "antsibull_ansible_version is _antsibull_packaging_version('9.0.0a1', '>=')"
+  ansible.builtin.set_fact:
+    antsibull_tags_validate: true
+    antsibull_tags_enforce_policy: true
+
 # Documentation for the following commands:
 # https://github.com/ansible-community/antsibull/blob/main/docs/build-ansible.rst
 
@@ -46,7 +49,7 @@
     {{ antsibull_build_command }} prepare {{ antsibull_ansible_version }}
       --data-dir {{ antsibull_data_dir }}
       {{ _feature_freeze | default('') }}
-      {{ _tags_file }}
+      {{ '--tags-file' if antsibull_tags_validate else '' }}
   # Minimal failure tolerance to galaxy collection download errors
   retries: 3
   delay: 5
@@ -56,6 +59,21 @@
     chdir: "{{ playbook_dir | dirname }}"
     creates: "{{ antsibull_data_dir }}/{{ _deps_file }}"
 
+- name: Find ignores file
+  when: antsibull_tags_validate
+  register: _ignores_stat
+  ansible.builtin.stat:
+    dest: "{{ antsibull_tags_ignores_file }}"
+
+- name: Validate tags file
+  when: antsibull_tags_validate
+  # ignore_errors creates conspicuous error messages without failing the playbook
+  ignore_errors: "{{ not antsibull_tags_enforce_policy }}"
+  ansible.builtin.command: >-
+    {{ antsibull_build_command }} validate-tags-file
+    {{ antsibull_data_dir }}/ansible-{{ antsibull_ansible_version }}-tags.yaml
+    {{ '--ignores-file ' ~ antsibull_tags_ignores_file if _ignores_stat.stat.exists else '' }}
+
 - name: Remove existing release tarball and wheel if they exist
   ansible.builtin.file:
     path: "{{ item }}"
@@ -74,7 +92,7 @@
       --build-file {{ antsibull_build_file }}
       --deps-file {{ _deps_file }}
       --debian
-      {{ _tags_file }}
+      {{ '--tags-file' if antsibull_tags_validate else '' }}
   # Minimal failure tolerance to galaxy collection download errors
   retries: 3
   delay: 5

src/antsibull/tagging.py

@@ -93,7 +93,8 @@ def _get_ignores(
     ignores = set(ignores)
     if ignore_fp:
         ignores.update(
-            line.strip() for line in ignore_fp if not line.startswith('#')
+            line.strip() for line in ignore_fp
+            if line.strip() and not line.startswith('#')
         )
     return ignores