Tagging - Add simple deprecations for purge_tags=False (ansible-colle…

…ctions#1185)

Tagging - Add simple deprecations for purge_tags=False

Depends-On: ansible-collections#844
SUMMARY
Deprecate the use of purge_tags=False as a default
ISSUE TYPE

Feature Pull Request

COMPONENT NAME
plugins/modules/aws_acm.py
plugins/modules/route53_health_check.py
plugins/modules/route53_zone.py
plugins/modules/sqs_queue.py
ADDITIONAL INFORMATION

Reviewed-by: Markus Bergholz <[email protected]>
Reviewed-by: Alina Buzachis <None>

aws_acm.py

@@ -28,8 +28,7 @@
 DOCUMENTATION = r'''
 ---
 module: aws_acm
-short_description: >
-  Upload and delete certificates in the AWS Certificate Manager service
+short_description: Upload and delete certificates in the AWS Certificate Manager service
 version_added: 1.0.0
 description:
   - >
@@ -45,7 +44,7 @@
   - >
     When I(state=present),
     if there is one certificate in ACM
-    with a C(Name) tag equal to the C(name_tag) parameter,
+    with a C(Name) tag equal to the I(name_tag) parameter,
     and an identical body and chain,
     this task will succeed without effect.
   - >
@@ -139,6 +138,12 @@
       - >
         If I(state=absent), you must provide exactly one of
         I(certificate_arn), I(domain_name) or I(name_tag).
+      - >
+        If both I(name_tag) and the 'Name' tag in I(tags) are set,
+        the values must be the same.
+      - >
+        If the 'Name' tag in I(tags) is not set and I(name_tag) is set,
+        the I(name_tag) value is copied to I(tags).
     type: str
     aliases: [name]
   private_key:
@@ -163,30 +168,14 @@
     default: present
     type: str
 
-  tags:
-    description:
-      - Tags to apply to certificates imported in ACM.
-      - >
-        If both I(name_tag) and the 'Name' tag in I(tags) are set,
-        the values must be the same.
-      - >
-        If the 'Name' tag in I(tags) is not set and I(name_tag) is set,
-        the I(name_tag) value is copied to I(tags).
-    type: dict
-    version_added: 3.2.0
-
-  purge_tags:
-    description:
-      - whether to remove tags not present in the C(tags) parameter.
-    default: false
-    type: bool
-    version_added: 3.2.0
-
+notes:
+  - Support for I(tags) and I(purge_tags) was added in release 3.2.0
 author:
   - Matthew Davis (@matt-telstra) on behalf of Telstra Corporation Limited
 extends_documentation_fragment:
   - amazon.aws.aws
   - amazon.aws.ec2
+  - amazon.aws.tags.deprecated_purge
 
 '''
 
@@ -504,8 +493,8 @@ def main():
         domain_name=dict(aliases=['domain']),
         name_tag=dict(aliases=['name']),
         private_key=dict(no_log=True),
-        tags=dict(type='dict'),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
         state=dict(default='present', choices=['present', 'absent']),
     )
     module = AnsibleAWSModule(
@@ -514,6 +503,14 @@ def main():
     )
     acm = ACMServiceManager(module)
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='community.aws')
+        module.params['purge_tags'] = False
+
     # Check argument requirements
     if module.params['state'] == 'present':
         # at least one of these should be specified.

route53_health_check.py

@@ -86,21 +86,14 @@
       - Will default to C(3) if not specified on creation.
     choices: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
     type: int
-  tags:
-    description:
-      - A hash/dictionary of tags to set on the health check.
-    type: dict
-    version_added: 2.1.0
-  purge_tags:
-    description:
-      - Delete any tags not specified in I(tags).
-    default: false
-    type: bool
-    version_added: 2.1.0
-author: "zimbatm (@zimbatm)"
+author:
+  - "zimbatm (@zimbatm)"
+notes:
+  - Support for I(tags) and I(purge_tags) was added in release 2.1.0.
 extends_documentation_fragment:
-- amazon.aws.aws
-- amazon.aws.ec2
+  - amazon.aws.aws
+  - amazon.aws.ec2
+  - amazon.aws.tags.deprecated_purge
 '''
 
 EXAMPLES = '''
@@ -432,8 +425,8 @@ def main():
         string_match=dict(),
         request_interval=dict(type='int', choices=[10, 30], default=30),
         failure_threshold=dict(type='int', choices=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]),
-        tags=dict(type='dict'),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
     )
 
     args_one_of = [
@@ -454,6 +447,14 @@ def main():
         supports_check_mode=True,
     )
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='community.aws')
+        module.params['purge_tags'] = False
+
     state_in = module.params.get('state')
     ip_addr_in = module.params.get('ip_address')
     port_in = module.params.get('port')

route53_zone.py

@@ -46,23 +46,14 @@
             - The reusable delegation set ID to be associated with the zone.
             - Note that you can't associate a reusable delegation set with a private hosted zone.
         type: str
-    tags:
-        description:
-            - A hash/dictionary of tags to add to the new instance or to add/remove from an existing one.
-        type: dict
-        version_added: 2.1.0
-    purge_tags:
-        description:
-            - Delete any tags not specified in the task that are on the zone.
-              This means you have to specify all the desired tags on each task affecting a zone.
-        default: false
-        type: bool
-        version_added: 2.1.0
 extends_documentation_fragment:
-- amazon.aws.aws
-- amazon.aws.ec2
-
-author: "Christopher Troup (@minichate)"
+    - amazon.aws.aws
+    - amazon.aws.ec2
+    - amazon.aws.tags.deprecated_purge
+notes:
+    - Support for I(tags) and I(purge_tags) was added in release 2.1.0.
+author:
+    - "Christopher Troup (@minichate)"
 '''
 
 EXAMPLES = r'''
@@ -445,8 +436,8 @@ def main():
         comment=dict(default=''),
         hosted_zone_id=dict(),
         delegation_set_id=dict(),
-        tags=dict(type='dict'),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
     )
 
     mutually_exclusive = [
@@ -460,6 +451,14 @@ def main():
         supports_check_mode=True,
     )
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='community.aws')
+        module.params['purge_tags'] = False
+
     zone_in = module.params.get('zone').lower()
     state = module.params.get('state').lower()
     vpc_id = module.params.get('vpc_id')

sqs_queue.py

@@ -87,20 +87,10 @@
     description:
       - Enables content-based deduplication. Used for FIFOs only.
       - Defaults to C(false).
-  tags:
-    description:
-      - Tag dict to apply to the queue.
-      - To remove all tags set I(tags={}) and I(purge_tags=true).
-    type: dict
-  purge_tags:
-    description:
-      - Remove tags not listed in I(tags).
-    type: bool
-    default: false
 extends_documentation_fragment:
   - amazon.aws.aws
   - amazon.aws.ec2
-
+  - amazon.aws.tags.deprecated_purge
 '''
 
 RETURN = r'''
@@ -483,11 +473,19 @@ def main():
         kms_master_key_id=dict(type='str'),
         kms_data_key_reuse_period_seconds=dict(type='int', aliases=['kms_data_key_reuse_period'], no_log=False),
         content_based_deduplication=dict(type='bool'),
-        tags=dict(type='dict'),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
     )
     module = AnsibleAWSModule(argument_spec=argument_spec, supports_check_mode=True)
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='community.aws')
+        module.params['purge_tags'] = False
+
     state = module.params.get('state')
     retry_decorator = AWSRetry.jittered_backoff(catch_extra_error_codes=['AWS.SimpleQueueService.NonExistentQueue'])
     try: