Clean up FILE_COMMON_ARGUMENTS (#66389)

* Clean up FILE_COMMON_ARGUMENTS.

* postgresql_pg_hba doesn't declare the backup option.

* uri doesn't declare the remote_src option.

* Add documentation.

* maven_artifact seems to use directory_mode, which it doesn't declare.

* Update changelogs/fragments/66389-file-common-arguments.yml
Update docs/docsite/rst/porting_guides/porting_guide_2.10.rst

ci_complete

Co-Authored-By: Jill R <4121322+jillr@users.noreply.github.com>

changelogs/fragments/66389-file-common-arguments.yml

@@ -0,0 +1,7 @@
+minor_changes:
+- "Ansible modules created with ``add_file_common_args=True`` added a number of undocumented
+   arguments which were mostly there to ease implementing certain action plugins. The undocumented
+   arguments ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``,
+   ``delimiter``, and ``directory_mode`` are now no longer added. Modules relying on these options
+   to be added need to specify them by themselves. Also, action plugins relying on these extra
+   elements in ``FILE_COMMON_ARGUMENTS`` need to be adjusted."

docs/docsite/rst/porting_guides/porting_guide_2.10.rst

@@ -96,6 +96,7 @@ The following modules will be removed in Ansible 2.14. Please update your playbo
 Noteworthy module changes
 -------------------------
 
+* Ansible modules created with ``add_file_common_args=True`` added a number of undocumented arguments which were mostly there to ease implementing certain action plugins. The undocumented arguments ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode`` are now no longer added. Modules relying on these options to be added need to specify them by themselves.
 * :ref:`vmware_datastore_maintenancemode <vmware_datastore_maintenancemode_module>` now returns ``datastore_status`` instead of Ansible internal key ``results``.
 * :ref:`vmware_host_kernel_manager <vmware_host_kernel_manager_module>` now returns ``host_kernel_status`` instead of Ansible internal key ``results``.
 * :ref:`vmware_host_ntp <vmware_host_ntp_module>` now returns ``host_ntp_status`` instead of Ansible internal key ``results``.
@@ -127,6 +128,7 @@ Noteworthy plugin changes
 -------------------------
 
 * The ``hashi_vault`` lookup plugin now returns the latest version when using the KV v2 secrets engine. Previously, it returned all versions of the secret which required additional steps to extract and filter the desired version.
+* Some undocumented arguments from ``FILE_COMMON_ARGUMENTS`` have been removed; plugins using these, in particular action plugins, need to be adjusted. The undocumented arguments which were removed are ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode``.
 
 Porting custom scripts
 ======================

lib/ansible/module_utils/basic.py

@@ -244,21 +244,6 @@ FILE_COMMON_ARGUMENTS = dict(
     selevel=dict(),
     setype=dict(),
     attributes=dict(aliases=['attr']),
-
-    # The following are not about perms and should not be in a rewritten file_common_args
-    src=dict(),  # Maybe dest or path would be appropriate but src is not
-    follow=dict(type='bool', default=False),  # Maybe follow is appropriate because it determines whether to follow symlinks for permission purposes too
-    force=dict(type='bool'),
-
-    # not taken by the file module, but other action plugins call the file module so this ignores
-    # them for now. In the future, the caller should take care of removing these from the module
-    # arguments before calling the file module.
-    content=dict(no_log=True),  # used by copy
-    backup=dict(),  # Used by a few modules to create a remote backup before updating the file
-    remote_src=dict(),  # used by assemble
-    regexp=dict(),  # used by assemble
-    delimiter=dict(),  # used by assemble
-    directory_mode=dict(),  # used by copy
     unsafe_writes=dict(type='bool'),  # should be available to any module using atomic_move
 )
 

lib/ansible/modules/database/postgresql/postgresql_pg_hba.py

@@ -666,6 +666,7 @@ def main():
     argument_spec = dict()
     argument_spec.update(
         address=dict(type='str', default='samehost', aliases=['source', 'src']),
+        backup=dict(type='bool', default=False),
         backup_file=dict(type='str'),
         contype=dict(type='str', default=None, choices=PG_HBA_TYPES),
         create=dict(type='bool', default=False),

lib/ansible/modules/files/copy.py

@@ -509,6 +509,7 @@ def main():
             remote_src=dict(type='bool'),
             local_follow=dict(type='bool'),
             checksum=dict(type='str'),
+            follow=dict(type='bool', default=False),
         ),
         add_file_common_args=True,
         supports_check_mode=True,

lib/ansible/modules/net_tools/basics/uri.py

@@ -584,6 +584,7 @@ def main():
         timeout=dict(type='int', default=30),
         headers=dict(type='dict', default={}),
         unix_socket=dict(type='path'),
+        remote_src=dict(type='bool', default=False),
     )
 
     module = AnsibleModule(

lib/ansible/modules/packaging/language/maven_artifact.py

@@ -563,7 +563,9 @@ def main():
             dest=dict(type="path", required=True),
             validate_certs=dict(required=False, default=True, type='bool'),
             keep_name=dict(required=False, default=False, type='bool'),
-            verify_checksum=dict(required=False, default='download', choices=['never', 'download', 'change', 'always'])
+            verify_checksum=dict(required=False, default='download', choices=['never', 'download', 'change', 'always']),
+            directory_mode=dict(type='str'),  # Used since https://github.com/ansible/ansible/pull/24965, not sure
+                                              # if this should really be here.
         ),
         add_file_common_args=True,
         mutually_exclusive=([('version', 'version_by_spec')])

lib/ansible/plugins/action/copy.py

@@ -37,12 +37,9 @@ from ansible.utils.hashing import checksum
 
 
 # Supplement the FILE_COMMON_ARGUMENTS with arguments that are specific to file
-# FILE_COMMON_ARGUMENTS contains things that are not arguments of file so remove those as well
 REAL_FILE_ARGS = frozenset(FILE_COMMON_ARGUMENTS.keys()).union(
                           ('state', 'path', '_original_basename', 'recurse', 'force',
-                           '_diff_peek', 'src')).difference(
-                          ('content', 'decrypt', 'backup', 'remote_src', 'regexp', 'delimiter',
-                           'directory_mode', 'unsafe_writes'))
+                           '_diff_peek', 'src'))
 
 
 def _create_remote_file_args(module_args):

test/sanity/ignore.txt

@@ -6540,6 +6540,7 @@ lib/ansible/modules/packaging/language/easy_install.py validate-modules:paramete
 lib/ansible/modules/packaging/language/gem.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/packaging/language/maven_artifact.py validate-modules:doc-missing-type
 lib/ansible/modules/packaging/language/maven_artifact.py validate-modules:parameter-type-not-in-doc
+lib/ansible/modules/packaging/language/maven_artifact.py validate-modules:undocumented-parameter
 lib/ansible/modules/packaging/language/pear.py validate-modules:doc-choices-do-not-match-spec
 lib/ansible/modules/packaging/language/pear.py validate-modules:doc-missing-type
 lib/ansible/modules/packaging/language/pear.py validate-modules:parameter-type-not-in-doc