From fae299708fb971d450a6874d25f62f5104db2e6d Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Mon, 9 Aug 2021 17:22:09 +0200
Subject: [PATCH] plugin attributes: make validate-modules strict again,
 improve version_added support (#74602)

* Add basic schema for attributes.

* Support attributes for version_added_collection adding mechanism.

* Add changelog fragment.

* Support new attribute properties from #74331.

* Require additional properties strictly.
---
 .../fragments/plugin_attributes-extension.yml |  3 ++
 lib/ansible/utils/plugin_docs.py              |  9 +++++
 .../validate_modules/schema.py                | 39 ++++++++++++++++++-
 3 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/fragments/plugin_attributes-extension.yml

diff --git a/changelogs/fragments/plugin_attributes-extension.yml b/changelogs/fragments/plugin_attributes-extension.yml
new file mode 100644
index 00000000000..f313bfb3040
--- /dev/null
+++ b/changelogs/fragments/plugin_attributes-extension.yml
@@ -0,0 +1,3 @@
+minor_changes:
+- "ansible-test - validate-modules now properly checks ``attributes`` for plugins (https://github.com/ansible/ansible/pull/74602)."
+- "ansible-doc - ``version_added`` in ``attributes`` now comes with ``version_added_collection`` (https://github.com/ansible/ansible/pull/74602)."
diff --git a/lib/ansible/utils/plugin_docs.py b/lib/ansible/utils/plugin_docs.py
index dc1160d4853..eb03dc081c9 100644
--- a/lib/ansible/utils/plugin_docs.py
+++ b/lib/ansible/utils/plugin_docs.py
@@ -89,6 +89,13 @@ def _process_versions_and_dates(fragment, is_module, return_docs, callback):
             if isinstance(return_value.get('contains'), MutableMapping):
                 process_return_values(return_value['contains'])
 
+    def process_attributes(attributes):
+        for attribute in attributes.values():
+            if not isinstance(attribute, MutableMapping):
+                continue
+            if 'version_added' in attribute:
+                callback(attribute, 'version_added', 'version_added_collection')
+
     if not fragment:
         return
 
@@ -102,6 +109,8 @@ def _process_versions_and_dates(fragment, is_module, return_docs, callback):
         process_deprecation(fragment['deprecated'], top_level=True)
     if isinstance(fragment.get('options'), MutableMapping):
         process_options(fragment['options'])
+    if isinstance(fragment.get('attributes'), MutableMapping):
+        process_attributes(fragment['attributes'])
 
 
 def add_collection_to_versions_and_dates(fragment, collection_name, is_module, return_docs=False):
diff --git a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py
index 3550d7204f4..07034530c13 100644
--- a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py
+++ b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py
@@ -524,11 +524,48 @@ def doc_schema(module_name, for_collection=False, deprecated_module=False):
         }
 
         doc_schema_dict.update(deprecation_required_scheme)
+
+    def add_default_attributes(more=None):
+        schema = {
+            'description': any_string_types,
+            'support': any_string_types,
+            'version_added_collection': any_string_types,
+            'version_added': any_string_types,
+        }
+        if more:
+            schema.update(more)
+        return schema
+
+    doc_schema_dict['attributes'] = Schema(
+        All(
+            Schema({
+                any_string_types: {
+                    Required('description'): any_string_types,
+                    Required('support'): Any('full', 'partial', 'none'),
+                    'version_added_collection': collection_name,
+                    'version_added': version(for_collection=for_collection),
+                },
+            }, extra=ALLOW_EXTRA),
+            partial(version_added, error_code='attribute-invalid-version-added', accept_historical=False),
+            Schema({
+                any_string_types: add_default_attributes(),
+                'action_group': add_default_attributes({
+                    Required('membership'): list_string_types,
+                }),
+                'forced_action_plugin': add_default_attributes({
+                    Required('action_plugin'): any_string_types,
+                }),
+                'proprietary': add_default_attributes({
+                    Required('platforms'): list_string_types,
+                }),
+            }, extra=PREVENT_EXTRA),
+        )
+    )
     return Schema(
         All(
             Schema(
                 doc_schema_dict,
-                extra=ALLOW_EXTRA
+                extra=PREVENT_EXTRA
             ),
             partial(version_added, error_code='module-invalid-version-added', accept_historical=not for_collection),
         )