From 9a39452a317fea825143a7239a63b11856f484ba Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 24 Sep 2020 15:33:22 -0400 Subject: [PATCH] update the definition of changed (#71865) * add nuance to the definition of changed, add notes to modules that return "changed" without changing state --- changelogs/fragments/changed_clarified.yml | 2 ++ .../docsite/rst/reference_appendices/common_return_values.rst | 4 ++-- lib/ansible/modules/add_host.py | 1 + lib/ansible/modules/group_by.py | 1 + 4 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/changed_clarified.yml diff --git a/changelogs/fragments/changed_clarified.yml b/changelogs/fragments/changed_clarified.yml new file mode 100644 index 00000000000..50d0eb26a33 --- /dev/null +++ b/changelogs/fragments/changed_clarified.yml @@ -0,0 +1,2 @@ +bugfixes: + - clarified changed status to reflect existing rule that had never been written down. diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 392dc96ce4a..34ca08c490e 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -23,11 +23,11 @@ For those modules that implement `backup=no|yes` when manipulating files, a path .. code-block:: console "backup_file": "./foo.txt.32729.2020-07-30@06:24:19~" - + changed ``````` -A boolean indicating if the task had to make changes. +A boolean indicating if the task had to make changes to the target or delegated host. .. code-block:: console diff --git a/lib/ansible/modules/add_host.py b/lib/ansible/modules/add_host.py index 3d8f8f7441b..f48140b8b17 100644 --- a/lib/ansible/modules/add_host.py +++ b/lib/ansible/modules/add_host.py @@ -37,6 +37,7 @@ notes: - Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source', because you can now have multiple sources. An example was added that shows how to partially restore the previous behaviour. - Windows targets are supported by this module. +- Though this module does not change the remote host, we do provide 'changed' status as it can be useful for those trying to track inventory changes. seealso: - module: ansible.builtin.group_by author: diff --git a/lib/ansible/modules/group_by.py b/lib/ansible/modules/group_by.py index 4a709d287ea..6b26117a387 100644 --- a/lib/ansible/modules/group_by.py +++ b/lib/ansible/modules/group_by.py @@ -31,6 +31,7 @@ options: notes: - Spaces in group names are converted to dashes '-'. - This module is also supported for Windows targets. +- Though this module does not change the remote host, we do provide 'changed' status as it can be useful for those trying to track inventory changes. seealso: - module: ansible.builtin.add_host author: