[stable-2.7] Prevent metadata changes in a stable branch (#48994) (#49131)

* [stable-2.7] Prevent metadata changes in a stable branch (#48994)
(cherry picked from commit 7287d39)

Co-authored-by: Matt Martz <matt@sivel.net>

* Fix metadata comparison

docs/docsite/rst/dev_guide/testing_validate-modules.rst

@@ -126,6 +126,7 @@ Errors
   331       argument in argument_spec must be a dictionary/hash when used
   332       ``AnsibleModule`` schema validation error
   333       ``ANSIBLE_METADATA.status`` of deprecated or removed can't include other statuses
+  334       ``ANSIBLE_METADATA`` cannot be changed in a point release for a stable branch
 
   ..
 ---------   -------------------

test/sanity/validate-modules/main.py

@@ -846,6 +846,7 @@ class ModuleValidator(Validator):
             filename_deprecated_or_removed = True
 
         # Have to check the metadata first so that we know if the module is removed or deprecated
+        metadata = None
         if not bool(doc_info['ANSIBLE_METADATA']['value']):
             self.reporter.error(
                 path=self.object_path,
@@ -853,7 +854,6 @@ class ModuleValidator(Validator):
                 msg='No ANSIBLE_METADATA provided'
             )
         else:
-            metadata = None
             if isinstance(doc_info['ANSIBLE_METADATA']['value'], ast.Dict):
                 metadata = ast.literal_eval(
                     doc_info['ANSIBLE_METADATA']['value']
@@ -971,7 +971,7 @@ class ModuleValidator(Validator):
                         self._validate_docs_schema(doc, doc_schema(self.object_name.split('.')[0]), 'DOCUMENTATION', 305)
 
                     self._check_version_added(doc)
-                    self._check_for_new_args(doc)
+                    self._check_for_new_args(doc, metadata)
 
             if not bool(doc_info['EXAMPLES']['value']):
                 self.reporter.error(
@@ -1286,13 +1286,13 @@ class ModuleValidator(Validator):
                     msg='"%s" is listed in DOCUMENTATION.options, but not accepted by the module' % arg
                 )
 
-    def _check_for_new_args(self, doc):
+    def _check_for_new_args(self, doc, metadata):
         if not self.base_branch or self._is_new_module():
             return
 
         with CaptureStd():
             try:
-                existing_doc = get_docstring(self.base_module, fragment_loader, verbose=True)[0]
+                existing_doc, dummy_examples, dummy_return, existing_metadata = get_docstring(self.base_module, fragment_loader, verbose=True)
                 existing_options = existing_doc.get('options', {}) or {}
             except AssertionError:
                 fragment = doc['extends_documentation_fragment']
@@ -1323,6 +1323,16 @@ class ModuleValidator(Validator):
         except ValueError:
             mod_version_added = StrictVersion('0.0')
 
+        if self.base_branch and 'stable-' in self.base_branch:
+            metadata.pop('metadata_version', None)
+            metadata.pop('version', None)
+            if metadata != existing_metadata:
+                self.reporter.error(
+                    path=self.object_path,
+                    code=334,
+                    msg=('ANSIBLE_METADATA cannot be changed in a point release for a stable branch')
+                )
+
         options = doc.get('options', {}) or {}
 
         should_be = '.'.join(ansible_version.split('.')[:2])