Deprecate default 'ignore' of 'image_name_mismatch'. (#703)

changelogs/fragments/703-docker_container-image_name_mismatch.yml

@@ -0,0 +1,5 @@
+deprecated_features:
+  - "docker_container - the default ``ignore`` for the ``image_name_mismatch`` parameter has been deprecated and will
+     switch to ``recreate`` in community.docker 4.0.0. A deprecation warning will be printed in situations where the
+     default value is used and where a behavior would change once the default changes
+     (https://github.com/ansible-collections/community.docker/pull/703)."

plugins/module_utils/module_container/module.py

@@ -321,9 +321,20 @@ def present(self, state):
             image_different = False
             if self.all_options['image'].comparison == 'strict':
                 image_different = self._image_is_different(image, container)
-                if self.param_image_name_mismatch == 'recreate' and self.param_image is not None and self.param_image != container.image_name:
-                    different = True
-                    self.diff_tracker.add('image_name', parameter=self.param_image, active=container.image_name)
+                if self.param_image_name_mismatch != 'ignore' and self.param_image is not None and self.param_image != container.image_name:
+                    if self.param_image_name_mismatch == 'recreate':
+                        different = True
+                        self.diff_tracker.add('image_name', parameter=self.param_image, active=container.image_name)
+                    else:
+                        # The default has been deprecated!
+                        self.module.deprecate(
+                            'The default value "ignore" for image_name_mismatch has been deprecated and will change to "recreate"'
+                            ' in community.docker 4.0.0. In the current situation, this would cause the container to be recreated'
+                            ' since the current container\'s image name "{active}" does not match the desired image name "{parameter}".'.format(
+                                parameter=self.param_image, active=container.image_name),
+                            version='4.0.0',
+                            collection_name='community.docker',
+                        )
             if image_different or different or self.param_recreate:
                 self.diff_tracker.merge(differences)
                 self.diff['differences'] = differences.get_legacy_docker_container_diffs()
@@ -839,7 +850,7 @@ def run_module(engine_driver):
             image=dict(type='str'),
             image_comparison=dict(type='str', choices=['desired-image', 'current-image'], default='desired-image'),
             image_label_mismatch=dict(type='str', choices=['ignore', 'fail'], default='ignore'),
-            image_name_mismatch=dict(type='str', choices=['ignore', 'recreate'], default='ignore'),
+            image_name_mismatch=dict(type='str', choices=['ignore', 'recreate']),
             keep_volumes=dict(type='bool', default=True),
             kill_signal=dict(type='str'),
             name=dict(type='str', required=True),

plugins/modules/docker_container.py

@@ -455,13 +455,14 @@
         does not match the image name provided to the module.
       - "This is ignored if C(image: ignore) is set in O(comparisons)."
       - If set to V(recreate) the container will be recreated.
-      - If set to V(ignore) the container will not be recreated because of this. It might still get recreated for other reasons.
+      - If set to V(ignore) (currently the default) the container will not be recreated because of this. It might still get recreated for other reasons.
         This has been the default behavior of the module for a long time, but might not be what users expect.
+      - Since community.docker 3.5.0, the default V(ignore) has been deprecated. If not specified, a deprecation warning
+        will be emitted if this setting would make a difference. The default will change to V(recreate) in community.docker 4.0.0.
     type: str
     choices:
       - recreate
       - ignore
-    default: ignore
     version_added: 3.2.0
   init:
     description: