Ansible style guide: be more specific about `when:`

[andreashaerter]

Proposed Rules for Writing when Conditions

1. Always use a list for when conditions:
   This ensures cleaner diffs when adding or removing conditions, making changes more readable and less error-prone.

2. Place | at the beginning of a line for piped expressions if they are so long a line-break is needed for readability:
   For conditions involving pipes (|), align each pipe at the start of a new line if the expression is long enough to warrant a line break. This improves readability in comparision to line break triggered by or (see following rule).

3. Use a line break after each unparenthesized or:
   When writing conditions involving or, break the line after each or unless it is within parentheses. This improves clarity and reduces ambiguity in complex logical expressions.

4. Do not use unparenthesized and; use separate list entries instead:
   For conditions involving and, avoid chaining them in a single line without parentheses. Instead, separate each condition into its own list entry. This improves clarity, aligns with Ansible style guidelines, and makes it easier to modify or extend conditions later.

---

Examples with Improved Formatting Based on These Rules:

Example 1

when:
  - ansible_version['full'] is version_compare(foobar_meta['galaxy_info']['min_ansible_version'], "<")

• Single condition, no changes required.

Example 2

when:
  - ansible_distribution is not defined or
    ansible_distribution_version is not defined or
    (foobar_meta['galaxy_info']['platforms'] | length) < 1

• Line breaks are correctly used after each or.

Example 3

when:
  - (foobar_meta['galaxy_info']['platforms'] | length) > 0
  - ansible_distribution is not defined or
    ansible_distribution_version is not defined or
    (foobar_meta['galaxy_info']['platforms'] | length) < 1
  - (foobar_meta['galaxy_info']['platforms']
     | selectattr('name', 'match', '^' + ansible_distribution + '$')
     | map(attribute='versions') | flatten
     | select('match', '^(' + ansible_distribution_version + '|all)$', ignorecase=true)
     | list | length) < 1

• Pipes (|) are correctly placed at the beginning of each line for readability.

Example 4

when:
  - condition_a
  - condition_b
  - condition_c

• Each condition is clearly visible and easy to understand.
• Adding or removing conditions becomes straightforward without introducing errors.

---

Benefits of These Rules:

• Ensures consistency across all when conditions.
• Improves readability of complex conditions, especially with or and pipes.
• Makes diffs cleaner and more maintainable when changes are made.