add rule docs part one

src/ansiblelint/rules/deprecated_module.md

@@ -14,7 +14,7 @@ Refer to the [Ansible module index](https://docs.ansible.com/ansible/latest/coll
   hosts: localhost
   tasks:
     - name: Configure VLAN ID
-      ansible.netcommon.net_vlan: # <-- This module is deprecated.
+      ansible.netcommon.net_vlan: # <- Uses a deprecated module.
         vlan_id: 20
 ```
 
@@ -26,7 +26,7 @@ Refer to the [Ansible module index](https://docs.ansible.com/ansible/latest/coll
   hosts: localhost
   tasks:
     - name: Configure VLAN ID
-      dellemc.enterprise_sonic.sonic_vlans: # <-- Use a platform specific module.
+      dellemc.enterprise_sonic.sonic_vlans: # <- Uses a platform specific module.
         config:
           - vlan_id: 20
 ```

src/ansiblelint/rules/empty_string_compare.md

@@ -0,0 +1,44 @@
+# empty-string-compare
+
+This rule checks for empty string comparison in playbooks.
+To ensure code clarity you should avoid using empty strings in conditional statements with the `when` clause.
+
+- Use `when: var|length > 0` instead of `when: var != ""`.
+- Use `when: var|length == 0` instead of `when: var == ""`.
+
+This is an opt-in rule.
+You must enable it in your Ansible-lint configuration as follows:
+
+```yaml
+enable_list:
+  - empty-string-compare
+```
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Shut down
+      ansible.builtin.command: /sbin/shutdown -t now
+      when: ansible_os_family == "" # <- Compares with an empty string.
+    - name: Shut down
+      ansible.builtin.command: /sbin/shutdown -t now
+      when: ansible_os_family !="" # <- Compares with an empty string.
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Shut down
+      ansible.builtin.shell: |
+        /sbin/shutdown -t now
+        echo $var ==
+      when: ansible_os_family
+```

src/ansiblelint/rules/fqcn_builtins.md

@@ -0,0 +1,25 @@
+# fqcn-builtins
+
+This rule checks that playbooks use the fully qualified collection name (FQCN) for modules in the `ansible.builtin` collection.
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Shell
+      shell: echo # <- This does not use the FQCN for the shell module.
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Shell
+      ansible.builtin.shell: echo # <- This uses the FQCN for the shell module.
+```

src/ansiblelint/rules/ignore_errors.md

@@ -0,0 +1,61 @@
+# ignore-errors
+
+This rule checks that playbooks do not use the `ignore_errors` directive to ignore all errors.
+Ignoring all errors in a playbook hides actual failures, incorrectly mark tasks as failed, and result in unexpected side effects and behavior.
+
+Instead of using the `ignore_errors: true` directive, you should do the following:
+
+- Ignore errors only when using the `{{ ansible_check_mode }}` variable.
+- Use `register` to register errors.
+- Use `failed_when:` and specify acceptable error conditions.
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Run apt-get update
+      ansible.builtin.command: apt-get update
+      ignore_errors: true # <- Ignores all errors, including important failures.
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Run apt-get update
+      ansible.builtin.command: apt-get update
+      ignore_errors: "{{ ansible_check_mode }}" # <- Ignores errors in check mode.
+```
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Run apt-get update
+      ansible.builtin.command: apt-get update
+      ignore_errors: true
+      register: ignore_errors_register # <- Stores errors and failures for evaluation.
+```
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Disable apport
+      become: "yes"
+      lineinfile:
+        line: "enabled=0"
+        dest: /etc/default/apport
+        mode: 0644
+        state: present
+      register: default_apport
+      failed_when: default_apport.rc !=0 and not default_apport.rc == 257 # <- Defines conditions that constitute a failure.
+```

src/ansiblelint/rules/inline_env_var.md

@@ -0,0 +1,37 @@
+# inline-env-var
+
+This rule checks that playbooks do not set environment variables in the `ansible.builtin.command` module.
+
+You should set environment variables with the `ansible.builtin.shell` module or the `environment` keyword.
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Set environment variable
+      ansible.builtin.command: MY_ENV_VAR=my_value # <- Sets an environment variable in the command module.
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Set environment variable
+      ansible.builtin.shell: echo $MY_ENV_VAR
+      environment: MY_ENV_VAR=my_value # <- Sets an environment variable with the environment keyword.
+```
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Set environment variable
+      ansible.builtin.shell: MY_ENV_VAR=my_value # <- Sets an environment variable with the shell module.
+```

src/ansiblelint/rules/literal_compare.md

@@ -0,0 +1,29 @@
+# literal-compare
+
+This rule checks for literal comparison with the `when` clause.
+Literal comparison, `when: var == True` or `when: not var`, is unnecessarily complex.
+Use `when: var` to keep your playbooks simple.
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Print environment variable to stdout
+      ansible.builtin.command: echo $MY_ENV_VAR
+      when: ansible_os_family == True # <- Adds complexity to your playbook.
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: all
+  tasks:
+    - name: Print environment variable to stdout
+      ansible.builtin.command: echo $MY_ENV_VAR
+      when: ansible_os_family # <- Keeps your playbook simple.
+```

src/ansiblelint/rules/meta_incorrect.md

@@ -0,0 +1,35 @@
+# meta-incorrect
+
+This rule checks role metadata for fields with undefined or default values.
+Always set appropriate values for the following metadata fields in the `meta/main.yml` file:
+
+- `author`
+- `description`
+- `company`
+- `license`
+
+## Problematic Code
+
+```yaml
+---
+# Metadata fields for the role contain default values.
+galaxy_info:
+  author: your name
+  description: your role description
+  company: your company (optional)
+  license: license (GPL-2.0-or-later, MIT, etc)
+```
+
+## Correct Code
+
+```yaml
+---
+galaxy_info:
+  author: Leroy Jenkins
+  description: Lorem ipsum dolor sit amet.
+  company: Red Hat
+  license: |
+    This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
+    To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/
+    or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+```

src/ansiblelint/rules/meta_incorrect.py

@@ -27,7 +27,9 @@ class MetaChangeFromDefaultRule(AnsibleLintRule):
         ("license", "license (GPL-2.0-or-later, MIT, etc)"),
     ]
     values = ", ".join(sorted({f[0] for f in field_defaults}))
-    description = f"meta/main.yml default values should be changed for: {values}"
+    description = (
+        f"You should set appropriate values in meta/main.yml for these fields: {values}"
+    )
     severity = "HIGH"
     tags = ["metadata"]
     version_added = "v4.0.0"

src/ansiblelint/rules/meta_no_info.md

@@ -0,0 +1,29 @@
+# meta-no-info
+
+This rule checks role metadata for missing information.
+Always set appropriate values for the following metadata fields in the `meta/main.yml` file:
+
+- `platform`
+- `min_ansible_version`
+
+## Problematic Code
+
+```yaml
+---
+# The metadata fields for minimum Ansible version and supported platforms are not set.
+galaxy_info:
+  min_ansible_version:
+  #platform:
+```
+
+## Correct Code
+
+```yaml
+---
+galaxy_info:
+  min_ansible_version: 2.8
+  platforms:
+    - name: Fedora
+      versions:
+        - all
+```

src/ansiblelint/rules/meta_no_tags.md

@@ -0,0 +1,22 @@
+# meta-no-tags
+
+This rule checks role metadata for tags with special characters.
+Always use lowercase numbers and letters for tags in the `meta/main.yml` file.
+
+## Problematic Code
+
+```yaml
+---
+# Metadata tags contain upper-case letters and special characters.
+galaxy_info:
+  galaxy_tags: [MyTag#1, MyTag&^-]
+```
+
+## Correct Code
+
+```yaml
+---
+# Metadata tags contain only lowercase letters and numbers.
+galaxy_info:
+  galaxy_tags: [mytag1, mytag2]
+```

src/ansiblelint/rules/meta_video_links.md

@@ -0,0 +1,34 @@
+# meta-video-links
+
+This rule checks formatting for video links in metadata.
+Always use dictionaries for items in the `meta/main.yml` file.
+
+Items in the `video_links` section must be in a dictionary and use the following keys:
+
+- `url`
+- `title`
+
+The value of the `url` key must be a shared link from YouTube, Vimeo, or Google Drive.
+
+## Problematic Code
+
+```yaml
+---
+galaxy_info:
+  video_links:
+    - https://youtu.be/this_is_not_a_dictionary # <- Does not use the url key.
+    - my_bad_key: https://youtu.be/aWmRepTSFKs # <- Uses an unsupported key.
+      title: Incorrect key.
+    - url: www.acme.com/vid # <- Uses an unsupported url format.
+      title: Incorrect url format.
+```
+
+## Correct Code
+
+```yaml
+---
+galaxy_info:
+  video_links:
+    - url: https://youtu.be/aWmRepTSFKs # <- Uses a supported shared link with the url key.
+      title: Correctly formatted video link.
+```

src/ansiblelint/rules/no_changed_when.md

@@ -0,0 +1,34 @@
+# no-changed-when
+
+This rule checks that tasks return changes to results or conditions.
+Unless tasks only read information, you should ensure that they return changes in the following ways:
+
+- Register results or conditions and use the `changed_when` clause.
+- Use the `creates` or `removes` argument.
+
+You should use the `when` clause to run tasks only if a check returns a particular result.
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook
+  hosts: localhost
+  tasks:
+    - name: Does not handle any output or return codes
+      ansible.builtin.command: cat {{ my_file|quote }} # <- Does not handle the command output.
+```
+
+## Correct Code
+
+```yaml
+---
+# This tasks registers the command`` output and
+- name: Example playbook
+  hosts: localhost
+  tasks:
+    - name: Handle shell output with return code
+      ansible.builtin.command: cat {{ my_file|quote }}
+      register: my_output # <- Registers the command output.
+      changed_when: my_output.rc != 0 # <- Uses the return code to define when the task has changed.
+```