Tagging - add docs fragment and update guidelines

docs/docsite/rst/dev_guidelines.rst

@@ -172,6 +172,20 @@ authentication parameters.  To do the same for your new module, add an entry for
   aws_module_name:
   - aws
 
+Module behavior
+---------------
+
+To reduce the chance of breaking changes occurring when new features are added,
+when a parameter is not explicitly set in a task, the module should avoid
+modifying the resource attribute.
+
+By convention, when a parameter is explicitly set in a task, the module should
+set the resource attribute to match what was set in the task.  In some cases,
+such as tags or associations, it can be helpful to add an additional parameter
+which changes this behavior to add the new setting to the attribute rather than
+replacing the current attributes.  Such a parameter should default to the
+replacive rather than additive behavior.
+
 .. _ansible_collections.amazon.aws.docsite.dev_module_connection:
 
 Connecting to AWS
@@ -526,18 +540,40 @@ and returns True if they are different.
 Dealing with tags
 =================
 
-AWS has a concept of resource tags. Usually the boto3 API has separate calls for tagging and
-untagging a resource.  For example, the ec2 API has a create_tags and delete_tags call.
+AWS has a concept of resource tags. Usually the boto3 API has separate calls
+for tagging and untagging a resource.  For example, the EC2 API has
+``create_tags`` and ``delete_tags`` calls.
+
+When adding tagging support, Ansible AWS modules should add a ``tags`` parameter
+that defaults to ``None`` and a ``purge_tags`` parameter that defaults to
+``True``.
+
+
+.. code-block:: python
+
+   argument_spec.update(
+       dict(
+           tags=dict(type='dict', required=False, default=None),
+           purge_tags=dict(type='bool', required=False, default=True),
+       )
+   )
+
+When the ``purge_tags`` parameter is set to ``True`` **and** the ``tags``
+parameter is explicitly set in the task, then any tags not explicitly set in
+``tags`` should be removed.
+
+If the ``tags`` parameter is not set then tags should not be modified, even if
+``purge_tags`` is set to ``True``.  This means that removing all tags requires
+``tags`` be explicitly set to an empty dictionary ``{}`` in the Ansible task.
 
-It is common practice in Ansible AWS modules to have a ``purge_tags`` parameter that defaults to
-true.
 
-The ``purge_tags`` parameter means that existing tags will be deleted if they are not specified by
-the Ansible task.
+There is a helper function ``compare_aws_tags`` to ease dealing with tags. It
+compares two dictionaries, the current tags and the desired tags, and returns
+the tags to set and the tags to delete.  See the Helper function section below
+for more detail.
 
-There is a helper function ``compare_aws_tags`` to ease dealing with tags. It can compare two dicts
-and return the tags to set and the tags to delete.  See the Helper function section below for more
-detail.
+There is also a documentation fragment ``amazon.aws.tags`` which should be
+included when adding tagging support.
 
 .. _ansible_collections.amazon.aws.docsite.dev_helpers:
 

plugins/doc_fragments/tags.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2022,  Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    # Minimum requirements for the collection
+    DOCUMENTATION = r'''
+options:
+  tags:
+    description:
+      - A dictionary representing the tags to be applied to the resource.
+      - If the I(tags) parameter is not set then tags will not be modified.
+    type: dict
+    required: false
+    aliases: ['resource_tags']
+  purge_tags:
+    description:
+      - If I(purge_tags=true) existing tags will be purged from the resource to
+        match exactly what is defined by I(tags) parameter.
+      - If the I(tags) parameter is not set then tags will not be modified.
+      - Tag keys beginning with C("aws:") are reserved by Amazon and can not be
+        modified.  As such they will be ignored for the purposes of the
+        I(purge_tags) parameter.  See the Amazon documentation for more information
+        U(https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions).
+    type: bool
+    default: true
+    required: false
+'''
+
+    # Minimum requirements for the collection
+    DEPRECATED_PURGE = r'''
+options:
+  tags:
+    description:
+      - A dictionary representing the tags to be applied to the resource.
+      - If the I(tags) parameter is not set then tags will not be modified.
+    type: dict
+    required: false
+    aliases: ['resource_tags']
+  purge_tags:
+    description:
+      - If I(purge_tags=true) existing tags will be purged from the resource to
+        match exactly what is defined by I(tags) parameter.
+      - If the I(tags) parameter is not set then tags will not be modified.
+      - Tag keys beginning with C("aws:") are reserved by Amazon and can not be
+        modified.  As such they will be ignored for the purposes of the
+        I(purge_tags) parameter.  See the Amazon documentation for more information
+        U(https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions).
+      - The current default value of C(False) has been deprecated.  The default
+        value will change to C(True) in release 5.0.0.
+    type: bool
+    required: false
+'''