Validate modules prevent version change (#51549)

* Add logic to catch version changes in docs

* Add in doc fragments before doing doc comparisons

* Handle new module scenario

* historical is only allowed in alreay present modules

* Don't repr StrictVersion

test/sanity/validate-modules/main.py

@@ -1005,8 +1005,10 @@ class ModuleValidator(Validator):
                         # This is the normal case
                         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, metadata)
+                    add_fragments(doc, self.object_path, fragment_loader=fragment_loader)
+
+                    existing_doc = self._check_for_new_args(doc, metadata)
+                    self._check_version_added(doc, existing_doc)
 
             if not bool(doc_info['EXAMPLES']['value']):
                 self.reporter.error(
@@ -1082,19 +1084,29 @@ class ModuleValidator(Validator):
 
         return doc_info, doc
 
-    def _check_version_added(self, doc):
-        if not self._is_new_module():
-            return
-
+    def _check_version_added(self, doc, existing_doc):
+        version_added_raw = doc.get('version_added')
         try:
             version_added = StrictVersion(str(doc.get('version_added', '0.0') or '0.0'))
         except ValueError:
             version_added = doc.get('version_added', '0.0')
+            if self._is_new_module() or version_added != 'historical':
+                self.reporter.error(
+                    path=self.object_path,
+                    code=306,
+                    msg='version_added is not a valid version number: %r' % version_added
+                )
+                return
+
+        if existing_doc and version_added_raw != existing_doc.get('version_added'):
             self.reporter.error(
                 path=self.object_path,
-                code=306,
-                msg='version_added is not a valid version number: %r' % version_added
+                code=307,
+                msg='version_added should be %r. Currently %r' % (existing_doc.get('version_added'),
+                                                                  version_added_raw)
             )
+
+        if not self._is_new_module():
             return
 
         should_be = '.'.join(ansible_version.split('.')[:2])
@@ -1105,7 +1117,7 @@ class ModuleValidator(Validator):
             self.reporter.error(
                 path=self.object_path,
                 code=307,
-                msg='version_added should be %s. Currently %s' % (should_be, version_added)
+                msg='version_added should be %r. Currently %r' % (should_be, version_added_raw)
             )
 
     def _validate_ansible_module_call(self, docs):
@@ -1377,6 +1389,19 @@ class ModuleValidator(Validator):
                 continue
 
             if any(name in existing_options for name in names):
+                for name in names:
+                    existing_version = existing_options.get(name, {}).get('version_added')
+                    if existing_version:
+                        break
+                current_version = details.get('version_added')
+                if current_version != existing_version:
+                    self.reporter.error(
+                        path=self.object_path,
+                        code=309,
+                        msg=('version_added for new option (%s) should '
+                             'be %r. Currently %r' %
+                             (option, existing_version, current_version))
+                    )
                 continue
 
             try:
@@ -1406,10 +1431,12 @@ class ModuleValidator(Validator):
                     path=self.object_path,
                     code=309,
                     msg=('version_added for new option (%s) should '
-                         'be %s. Currently %s' %
+                         'be %r. Currently %r' %
                          (option, should_be, version_added))
                 )
 
+        return existing_doc
+
     @staticmethod
     def is_blacklisted(path):
         base_name = os.path.basename(path)