Add 'idempotent' attribute (#217)

* Add 'idempotent' attribute. * Add attributes to install role. * Mention check mode in attribute description. Co-authored-by: Alexei Znamensky <[email protected]> --------- Co-authored-by: Alexei Znamensky <[email protected]>
ansible-collections · Dec 30, 2024 · d7d823b · d7d823b
1 parent 9f2e345
commit d7d823b
Show file tree

Hide file tree

Showing 4 changed files with 51 additions and 0 deletions.
diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
@@ -18,6 +18,20 @@ class ModuleDocFragment(object):
     description: Can run in C(check_mode) and return changed status prediction without modifying target.
   diff_mode:
     description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+  idempotent:
+    description:
+      - When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+      - This assumes that the system controlled/queried by the module has not changed in a relevant way.
+"""
+
+    # Should be used together with the standard fragment
+    IDEMPOTENT_NOT_MODIFY_STATE = r"""
+options: {}
+attributes:
+  idempotent:
+    support: full
+    details:
+      - This action does not modify state.
 """
 
     # Should be used together with the standard fragment

diff --git a/plugins/modules/load_vars.py b/plugins/modules/load_vars.py
@@ -62,6 +62,10 @@
       - This action does not modify state.
   facts:
     support: full
+  idempotent:
+    support: N/A
+    details:
+      - The action has no C(changed) state.
 seealso:
   - module: ansible.builtin.set_fact
   - module: ansible.builtin.include_vars

diff --git a/plugins/modules/sops_encrypt.py b/plugins/modules/sops_encrypt.py
@@ -63,6 +63,8 @@
     support: none
   safe_file_operations:
     support: full
+  idempotent:
+    support: full
 seealso:
   - plugin: community.sops.sops
     plugin_type: lookup

diff --git a/roles/install/meta/argument_specs.yml b/roles/install/meta/argument_specs.yml
@@ -70,3 +70,34 @@ argument_specs:
           - Should mainly be used in GitHub Actions.
         type: str
         version_added: 1.6.0
+    attributes:
+      check_mode:
+        description: Can run in C(check_mode) and return changed status prediction without modifying target.
+        support: none
+        details:
+          - The role currently does not work in check mode.
+          # TODO: add 'check_mode: false' to tasks that prepare something
+      diff_mode:
+        description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+        support: partial
+        details:
+          - The role supports diff mode if the M(ansible.builtin.package) action for the system supports it.
+      idempotent:
+        description:
+          - When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+          - This assumes that the system controlled/queried by the module has not changed in a relevant way.
+        support: partial
+        details:
+          - The role is idempotent if the M(ansible.builtin.package) action for the system is idempotent.
+          - This is usually the case, but if packages need to be installed from GitHub (that is, through an URL), idempotence might not hold.
+      platform:
+        description: Target OS/families that can be operated against.
+        support: full
+        platforms:
+          - Alpine (new enough)
+          - Arch Linux
+          - CentOS 7, Stream 8, or newer
+          - Debian 10 (Buster) or newer
+          - Fedora (new enough)
+          - RHEL 7 or newer
+          - Ubuntu 16.04 or newer LTS versions