Make docker_stack adhere to standard ansible return values (#63467)

* Make docker_stack adhere to standard return values

The names of the various fields returned from ansible modules are e.g defined here https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#msg.

Adhering to this improves usability and makes use of functionality for e.g stdout_lines etc.

* Update lib/ansible/modules/cloud/docker/docker_stack.py

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Fix under-indentation of continuation line (pep8)

Issue exposed in test here https://app.shippable.com/github/ansible/ansible/runs/146667/1/console

* Don't break old playbooks/roles

Made sure the changes are only adding new variables, not removing anything existing yet.

* Added comment

* Minor fixes

* Update lib/ansible/modules/cloud/docker/docker_stack.py

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/cloud/docker/docker_stack.py

Co-Authored-By: Felix Fontein <felix@fontein.de>

* minor change to docker_stack.py

* Add changelog fragment for PR 63467

* Format changelog fragment

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Add fragment about docker_stack return val depr

* Add docker_stack doc note about deprecated vals

* Remove whitespace in empty line

* Add docker_stack depr notice to porting guide

* Update changelogs/fragments/63467-docker-stack-return-fix.yml

Co-Authored-By: Felix Fontein <felix@fontein.de>

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

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/cloud/docker/docker_stack.py

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Added back a missing new line

changelogs/fragments/63467-docker-stack-return-fix.yml

@@ -0,0 +1,5 @@
+minor_changes:
+  - docker_stack - Added ``stdout``, ``stderr``, and ``rc`` to return values.
+
+deprecated_features:
+  - docker_stack - Return values ``out`` and ``err`` have been deprecated and will be removed in Ansible 2.14. Use ``stdout`` and ``stderr`` instead.

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

@@ -56,7 +56,7 @@ The following functionality will be removed in Ansible 2.14. Please update updat
 * :ref:`iam_managed_policy <iam_managed_policy_module>`: the ``fail_on_delete`` option wil be removed.  It has always been ignored by the module.
 * :ref:`s3_lifecycle <s3_lifecycle_module>`: the ``requester_pays`` option will be removed. It has always been ignored by the module.
 * :ref:`s3_sync <s3_sync_module>`: the ``retries`` option will be removed. It has always been ignored by the module.
-
+* The return values ``err`` and ``out`` of :ref:`docker_stack <docker_stack_module>` have been deprecated. Use ``stdout`` and ``stderr`` from now on instead.
 
 The following functionality will change in Ansible 2.14. Please update update your playbooks accordingly.
 

lib/ansible/modules/cloud/docker/docker_stack.py

@@ -81,6 +81,9 @@ options:
 requirements:
   - jsondiff
   - pyyaml
+
+notes:
+  - Return values I(out) and I(err) have been deprecated and will be removed in Ansible 2.14. Use I(stdout) and I(stderr) instead.
 '''
 
 RETURN = '''
@@ -261,8 +264,9 @@ def main():
 
         if rc != 0:
             module.fail_json(msg="docker stack up deploy command failed",
-                             out=out,
+                             rc=rc,
-                             rc=rc, err=err)
+                             out=out, err=err,  # Deprecated
+                             stdout=out, stderr=err)
 
         before_after_differences = json_diff(before_stack_services,
                                              after_stack_services)
@@ -274,10 +278,17 @@ def main():
                     before_after_differences.pop(k)
 
         if not before_after_differences:
-            module.exit_json(changed=False)
+            module.exit_json(
+                changed=False,
+                rc=rc,
+                stdout=out,
+                stderr=err)
         else:
             module.exit_json(
                 changed=True,
+                rc=rc,
+                stdout=out,
+                stderr=err,
                 stack_spec_diff=json_diff(before_stack_services,
                                           after_stack_services,
                                           dump=True))
@@ -287,11 +298,14 @@ def main():
             rc, out, err = docker_stack_rm(module, name, absent_retries, absent_retries_interval)
             if rc != 0:
                 module.fail_json(msg="'docker stack down' command failed",
-                                 out=out,
                                  rc=rc,
-                                 err=err)
+                                 out=out, err=err,  # Deprecated
+                                 stdout=out, stderr=err)
             else:
-                module.exit_json(changed=True, msg=out, err=err, rc=rc)
+                module.exit_json(changed=True,
+                                 msg=out, rc=rc,
+                                 err=err,  # Deprecated
+                                 stdout=out, stderr=err)
         module.exit_json(changed=False)