From 85925eabea1abb9a9f29dde6fd9081970453719e Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Tue, 15 Mar 2022 11:45:47 +0100
Subject: [PATCH] Add description on keeping old behavior and already switching
 to new behavior. (#4361)

---
 plugins/modules/packaging/os/pacman.py | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/plugins/modules/packaging/os/pacman.py b/plugins/modules/packaging/os/pacman.py
index 3b0fc5c599..79fe159591 100644
--- a/plugins/modules/packaging/os/pacman.py
+++ b/plugins/modules/packaging/os/pacman.py
@@ -83,6 +83,8 @@ options:
             - If not specified, it defaults to C(false).
             - Please note that this option will only have an influence on the module's C(changed) state
               if I(name) and I(upgrade) are not specified. This will change in community.general 5.0.0.
+              See the examples for how to make the module behave as it will in 5.0.0 right now, or how
+              to keep the current behavior with 5.0.0 and later.
         type: bool
         aliases: [ update-cache ]
 
@@ -210,6 +212,26 @@ EXAMPLES = """
   # The 'changed' state of this call will only indicate whether
   # something was upgraded, but not on whether the cache was
   # updated. This will change in community.general 5.0.0!
+  #
+  # To keep the old behavior, add the following to the task:
+  #
+  #   register: result
+  #   changed_when: result.packages | length > 0
+  #
+  # To already switch to the new behavior now, add:
+  #
+  #   register: result
+  #   changed_when: result is changed or result.cache_updated
+  #
+  # Note that both constructs only work with community.general 4.6.0+.
+  # For compatibility with older versions of community.general, you
+  # have to use
+  #
+  #   changed_when: result.packages | default([]) | length > 0
+  #
+  # respectively
+  #
+  #   changed_when: result is changed or (result.cache_updated | default(false))
   community.general.pacman:
     update_cache: yes
     upgrade: yes