From 2fe34b6444502079dc0b84365ce82dbc92de308e Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sat, 13 Apr 2024 14:06:49 +0200
Subject: Adding upstream version 6.17.2.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 src/ansiblelint/rules/no_handler.md | 55 +++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 src/ansiblelint/rules/no_handler.md

(limited to 'src/ansiblelint/rules/no_handler.md')

diff --git a/src/ansiblelint/rules/no_handler.md b/src/ansiblelint/rules/no_handler.md
new file mode 100644
index 0000000..4deccaa
--- /dev/null
+++ b/src/ansiblelint/rules/no_handler.md
@@ -0,0 +1,55 @@
+# no-handler
+
+This rule checks for the correct handling of changes to results or conditions.
+
+If a task has a `when: result.changed` condition, it effectively acts as a
+[handler](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_handlers.html#handlers).
+The recommended approach is to use `notify` and move tasks to `handlers`.
+If necessary you can silence the rule by add a `# noqa: no-handler` comment at the end of the line.
+
+## Problematic Code
+
+```yaml
+---
+- name: Example of no-handler rule
+  hosts: localhost
+  tasks:
+    - name: Register result of a task
+      ansible.builtin.copy:
+        dest: "/tmp/placeholder"
+        content: "Ansible made this!"
+        mode: 0600
+      register: result # <-- Registers the result of the task.
+    - name: Second command to run
+      ansible.builtin.debug:
+        msg: The placeholder file was modified!
+      when: result.changed # <-- Triggers the no-handler rule.
+```
+
+```yaml
+---
+# Optionally silences the rule.
+when: result.changed # noqa: no-handler
+```
+
+## Correct Code
+
+The following code includes the same functionality as the problematic code without recording a `result` variable.
+
+```yaml
+---
+- name: Example of no-handler rule
+  hosts: localhost
+  tasks:
+    - name: Register result of a task
+      ansible.builtin.copy:
+        dest: "/tmp/placeholder"
+        content: "Ansible made this!"
+        mode: 0600
+      notify:
+        - Second command to run # <-- Handler runs only when the file changes.
+  handlers:
+    - name: Second command to run
+      ansible.builtin.debug:
+        msg: The placeholder file was modified!
+```
-- 
cgit v1.2.3