x509_crl: prepare releasing the mode option for AnsibleModule's use (#596)

* Prepare releasing the mode option for AnsibleModule's use.

* Update docs.

plugins/modules/x509_crl.py

@@ -42,7 +42,7 @@ options:
         default: present
         choices: [ absent, present ]
 
-    mode:
+    crl_mode:
         description:
             - Defines how to process entries of existing CRLs.
             - If set to C(generate), makes sure that the CRL has the exact set of revoked certificates
@@ -51,8 +51,20 @@ options:
               I(revoked_certificates), but can also contain other revoked certificates. If the CRL file
               already exists, all entries from the existing CRL will also be included in the new CRL.
               When using C(update), you might be interested in setting I(ignore_timestamps) to C(true).
+            - The default value is C(generate).
+            - This parameter was called I(mode) before community.crypto 2.13.0. It has been renamed to avoid
+              a collision with the common I(mode) parameter for setting the CRL file's access mode.
         type: str
-        default: generate
+        # default: generate
+        choices: [ generate, update ]
+        version_added: 2.13.0
+    mode:
+        description:
+            - This parameter has been renamed to I(crl_mode). The old name I(mode) is now deprecated and will
+              be removed in community.crypto 3.0.0. Replace usage of this parameter with I(crl_mode).
+            - Note that from community.crypto 3.0.0 on, I(mode) will be used for the CRL file's mode.
+        type: str
+        # default: generate
         choices: [ generate, update ]
 
     force:
@@ -479,7 +491,7 @@ class CRL(OpenSSLObject):
 
         self.format = module.params['format']
 
-        self.update = module.params['mode'] == 'update'
+        self.update = module.params['crl_mode'] == 'update'
         self.ignore_timestamps = module.params['ignore_timestamps']
         self.return_content = module.params['return_content']
         self.name_encoding = module.params['name_encoding']
@@ -827,7 +839,18 @@ def main():
     module = AnsibleModule(
         argument_spec=dict(
             state=dict(type='str', default='present', choices=['present', 'absent']),
-            mode=dict(type='str', default='generate', choices=['generate', 'update']),
+            crl_mode=dict(
+                type='str',
+                # default='generate',
+                choices=['generate', 'update'],
+            ),
+            mode=dict(
+                type='str',
+                # default='generate',
+                choices=['generate', 'update'],
+                removed_in_version='3.0.0',
+                removed_from_collection='community.crypto',
+            ),
             force=dict(type='bool', default=False),
             backup=dict(type='bool', default=False),
             path=dict(type='path', required=True),
@@ -882,6 +905,14 @@ def main():
         add_file_common_args=True,
     )
 
+    if module.params['mode']:
+        if module.params['crl_mode']:
+            module.fail_json('You cannot use both `mode` and `crl_mode`. Use `crl_mode`.')
+        module.params['crl_mode'] = module.params['mode']
+    # TODO: in 3.0.0, once the option `mode` has been removed, remove this:
+    module.params.pop('mode', None)
+    # From then on, `mode` will be the file mode of the CRL file
+
     if not CRYPTOGRAPHY_FOUND:
         module.fail_json(msg=missing_required_lib('cryptography >= {0}'.format(MINIMAL_CRYPTOGRAPHY_VERSION)),
                          exception=CRYPTOGRAPHY_IMP_ERR)