Merge branch 'main' into chore/schemas

.ansible-lint

@@ -1,8 +1,11 @@
 ---
 # .ansible-lint
+
+profile: null # min, basic, moderate,safety, shared, production
+
 # exclude_paths included in this file are parsed relative to this file's location
 # and not relative to the CWD of execution. CLI arguments passed to the --exclude
-# option will be parsed relative to the CWD of execution.
+# option are parsed relative to the CWD of execution.
 exclude_paths:
   - .cache/ # implicit unless exclude_paths is defined in config
   - .github/
@@ -37,12 +40,12 @@ use_default_rules: true
 # rulesdir:
 #   - ./rule/directory/
 
-# This makes linter to fully ignore rules/tags listed below
+# Ansible-lint completely ignores rules or tags listed below
 skip_list:
   - skip_this_tag
 
-# Any rule that has the 'opt-in' tag will not be loaded unless its 'id' is
-# mentioned in the enable_list:
+# Ansible-lint does not automatically load rules that have the 'opt-in' tag.
+# You must enable opt-in rules by listing each rule 'id' below.
 enable_list:
   - empty-string-compare # opt-in
   - no-log-password # opt-in
@@ -54,7 +57,7 @@ enable_list:
 # tags:
 #   - jinja[spacing]
 
-# This makes the linter display but not fail for rules/tags listed below:
+# Ansible-lint does not fail on warnings from the rules or tags listed below
 warn_list:
   - skip_this_tag
   - experimental # experimental is included in the implicit list
@@ -72,6 +75,11 @@ warn_list:
 # Offline mode disables installation of requirements.yml
 offline: false
 
+# Return success if number of violations compared with previous git
+# commit has not increased. This feature works only in git
+# repositories.
+progressive: false
+
 # Define required Ansible's variables to satisfy syntax check
 extra_vars:
   foo: bar

.config/dictionary.txt

@@ -18,6 +18,7 @@ Sshell
 TOXENV
 TYPECHECK
 WSLENV
+aarch64
 abspath
 addoption
 addopts
@@ -139,8 +140,6 @@ lineinfile
 linkcheck
 lintable
 lintables
-listrules
-listtags
 literalinclude
 localectl
 matchdir

.github/workflows/tox.yml

@@ -209,6 +209,7 @@ jobs:
 
       - name: Initialize tox envs ${{ matrix.tox_env }}
         run: python3 -m tox --notest --skip-missing-interpreters false -vv -e ${{ matrix.tox_env }}
+        timeout-minutes: 3 # average is under 1
 
       # sequential run improves browsing experience (almost no speed impact)
       - name: "Test with tox: ${{ matrix.tox_env }}"

.packit.yaml

@@ -17,10 +17,13 @@ jobs:
   - job: copr_build
     metadata:
       targets:
-        # - fedora-34  # has no https://src.fedoraproject.org/rpms/python-build
-        - fedora-35
-        - fedora-36
-        # - centos-stream-9  # has no https://src.fedoraproject.org/rpms/python-build
+        # See https://packit.dev/docs/configuration/#aliases
+        # API to get available targets: https://api.dev.testing-farm.io/v0.1/composes/public
+        - fedora-stable
+        - fedora-development
+        # Missing python3-build see https://bugzilla.redhat.com/show_bug.cgi?id=2129071
+        # - centos-stream-9-aarch64
+        # - centos-stream-9-x86_64
     trigger: pull_request
   # - job: tests
   #   trigger: pull_request

docs/configuring.md

@@ -1,26 +1,35 @@
-(configuring-lint)=
+(configuring-ansible-lint)=
 
-# Configuring
+# Configuration
 
 ```{contents} Topics
 
 ```
 
-## Configuration File
+Customize how Ansible-lint runs against automation content to suit your needs.
+You can ignore certain rules, enable `opt-in` rules, and control various other settings.
 
-Ansible-lint supports local configuration via a `.ansible-lint` or
-`.config/ansible-lint.yml` configuration files. Ansible-lint checks the
-working directory for the presence of this file and applies any configuration
-found there. The configuration file location can also be overridden via the
-`-c path/to/file` CLI flag.
+Ansible-lint loads configuration from a file in the current working directory or from a file that you specify in the command line.
+If you provide configuration on both via a config file and on the command line, list values are merged (for example `exclude_paths`) and **True** is preferred for boolean values like `quiet`.
 
-When configuration file is not found in current directory, the tool will try
-to look for one in parent directories but it will not go outside current git
-repository.
+## Using local configuration files
 
-If a value is provided on both the command line and via a config file, the
-values will be merged (if a list like **exclude_paths**), or the **True** value
-will be preferred, in the case of something like **quiet**.
+Specify Ansible-lint configuration in either `.ansible-lint` or `.config/ansible-lint.yml` in your current working directory.
+
+```{note}
+If Ansible-lint cannot find a configuration file in the current directory it attempts to locate it in a parent directory.
+However Ansible-lint does not try to load configuration that is outside the git repository.
+```
+
+## Specifying configuration files
+
+Use the `-c <filename>` CLI flag with command line invocations of Ansible-lint, for example:
+
+```bash
+ansible-lint -c path/to/ansible-lint-dev.yml
+```
+
+## Ansible-lint configuration
 
 The following values are supported, and function identically to their CLI
 counterparts:
@@ -29,12 +38,11 @@ counterparts:
 :language: yaml
 ```
 
-## Pre-commit Setup
+## Pre-commit setup
+
+To use Ansible-lint with [pre-commit], add the following to the `.pre-commit-config.yaml` file in your local repository.
 
-To use ansible-lint with [pre-commit], just add the following to your local
-repo's `.pre-commit-config.yaml` file. Make sure to change **rev:** to be
-either a git commit sha or tag of ansible-lint containing
-`.pre-commit-hooks.yaml`.
+Change **rev:** to either a commit sha or tag of Ansible-lint that contains `.pre-commit-hooks.yaml`.
 
 ```yaml
 - repo: https://github.com/ansible/ansible-lint.git

docs/custom-rules.md

@@ -1,32 +1,33 @@
-# Custom Rules
+(defining-custom-rules)=
 
-## Creating Custom Rules
+# Custom linting rules
 
-Rules are described using a class file per rule. Default rules are named
-_DeprecatedVariableRule.py_, etc.
+Define and use your own sets of rules with Ansible-lint.
 
-Each rule definition should have the following:
+## Rule definitions
 
-- ID: A unique identifier
+You define each custom rule in a unique Python class file.
+Default rules are named _DeprecatedVariableRule.py_, etc.
 
-- Short description: Brief description of the rule
+Each rule should have a short description as a Python docstring wrapped in triple quotes `"""` immediately after the class name.
+The short description should be brief and meaningfully explain the purpose of the rule to users.
 
-- Description: What the rule is looking for
+Each rule definition should have the following parts:
 
-- Tags: One or more tags that may be used to include or exclude the rule
+- `id` provides a unique identifier to the rule.
+- `description` explains what the rule checks for.
+- `tags` specifies one or more tags for including or excluding the rule.
 
-- At least one of the following methods:
+### Match and matchtask methods
 
-  - `match` that takes a line and returns None or False, if the line doesn't
-    match the test, and True or a custom message, when it does. (This allows
-    one rule to test multiple behaviors - see e.g. the
-    _CommandsInsteadOfModulesRule_.)
-  - `matchtask` that operates on a single task or handler, such that tasks
-    get standardized to always contain a _module_ key and _module_arguments_
-    key. Other common task modifiers, such as _when_, _with_items_, etc., are
-    also available as keys, if present in the task.
+Each rule definition should also invoke one of the following methods:
 
-An example rule using `match` is:
+- `match` takes a line and returns:
+  - None or False if the line does not match the test.
+  - True or a custom message if the line does match the test. (This allows one rule to test multiple behaviors - see e.g. the _CommandsInsteadOfModulesRule_.)
+- `matchtask` operates on a single task or handler, such that tasks get standardized to always contain a _module_ key and _module_arguments_ key. Other common task modifiers, such as _when_, _with_items_, etc., are also available as keys if present in the task.
+
+The following is an example rule that uses the `match` method:
 
 ```python
 from ansiblelint.rules import AnsibleLintRule
@@ -43,7 +44,7 @@ class DeprecatedVariableRule(AnsibleLintRule):
         return '${' in line
 ```
 
-An example rule using `matchtask` is:
+The following is an example rule that uses the `matchtask` method:
 
 ```python
 from typing import TYPE_CHECKING, Any, Dict, Union
@@ -88,29 +89,25 @@ In ansible-lint 3.0.0 `task['action']['module']` was renamed
 module as an argument. As a precaution, `task['action']['module_arguments']`
 was renamed `task['action']['__ansible_arguments__']`.
 
-## Packaging Custom Rules
+## Packaging custom rules
 
-Ansible-lint provides a sub directory named _custom_ in its built-in rules,
-`/usr/lib/python3.8/site-packages/ansiblelint/rules/custom/` for example, to
-install custom rules since v4.3.1. The custom rules which are packaged as a
-python package installed into this directory will be loaded and enabled
-automatically by ansible-lint.
+Ansible-lint automatically loads and enables custom rules in Python packages from the _custom_ subdirectory.
+This subdirectory is part of the Ansible-lint installation directory, for example:
 
-To make custom rules loaded automatically, you need the following:
+`/usr/lib/python3.8/site-packages/ansiblelint/rules/custom/`
 
-- Packaging your custom rules as a python package named some descriptive ones
-  like `ansible_lint_custom_rules_foo`.
-- Make it installed into
-  `<ansible_lint_custom_rules_dir>/custom/<your_custom_rules_subdir>/`.
+To automatically load custom rules, do the following:
 
-You may accomplish the second by adding some configurations into the \[options\]
-section of the `setup.cfg` of your custom rules python package like the
-following.
+1. Package your custom rules as a Python package with a descriptive name.
 
-```
-[options]
-packages =
-    ansiblelint.rules.custom.<your_custom_rules_subdir>
-package_dir =
-    ansiblelint.rules.custom.<your_custom_rules_subdir> = <your_rules_source_code_subdir>
-```
+2. Configure the \[options\] section of the `setup.cfg` of your custom rules Python package as in the following example:
+
+   ```yaml
+   [options]
+   packages =
+       ansiblelint.rules.custom.<your_custom_rules_subdir>
+   package_dir =
+       ansiblelint.rules.custom.<your_custom_rules_subdir> = <your_rules_source_code_subdir>
+   ```
+
+3. Install the Python package into `<ansible_lint_custom_rules_dir>/custom/<your_custom_rules_subdir>/`.

docs/index.md

@@ -38,7 +38,7 @@ Philosophy<philosophy>
 installing
 usage
 configuring
-profiles
+using-profiles
 rules
 ```
 

docs/installing.md

@@ -6,34 +6,44 @@
 
 ```
 
-Installing on Windows is not supported because we use symlinks inside Python
-packages.
+Install Ansible-lint to apply rules and follow best practices with your automation content.
 
-Our project does not ship a container. Please avoid raising any bugs
-related to containers and use the [discussions](https://github.com/ansible/ansible-lint/discussions) forum instead.
+```{note}
+Ansible-lint does not currently support installation on Windows systems.
+```
+
+For a container image, we recommend using [creator-ee](https://github.com/ansible/creator-ee/), which includes Ansible-lint.
+If you have a use case that the `creator-ee` container does satisfy, please contact the team through the [discussions](https://github.com/ansible/ansible-lint/discussions) forum.
 
-We recommend you to try [creator-ee](https://github.com/ansible/creator-ee/),
-which is a container that also carries ansible-lint.
+You can also run Ansible-lint on your source code with the [Ansible-lint GitHub action](https://github.com/marketplace/actions/ansible-lint) instead of installing it directly.
 
-## Using pip or pipx
+## Installing the latest version
 
-You can use either [pip3] or [pipx] to install it; the latter one
-automatically isolates the linter from your current python environment.
-That approach may avoid having to deal with particularities of installing
-python packages, like creating a virtual environment, activating it, installing
-using `--user` or fixing potential conflicts if not using virtualenvs.
+You can install the most recent version of Ansible-lint with the [pip3] or [pipx] Python package manager.
+Use [pipx] to isolate Ansible-lint from your current Python environment as an alternative to creating a virtual environment.
 
 ```bash
-# This will also install ansible-core if needed
+# This also installs ansible-core if it is not already installed
 pip3 install "ansible-lint"
 ```
 
-(installing-from-source)=
+## Installing on Fedora and RHEL
+
+You can install Ansible-lint on Fedora, or Red Hat Enterprise Linux (RHEL) with the `dnf` package manager.
+
+```bash
+dnf install ansible-lint
+```
+
+```{note}
+On RHEL, `ansible-lint` package is part of "Red Hat Ansible Automation Platform" subscription, which needs
+to be activated.
+```
 
-## From Source
+## Installing from source code
 
-**Note**: pip 19.0+ is required for installation. Please consult with the
-[PyPA User Guide] to learn more about managing Pip versions.
+**Note**: pip 19.0+ is required for installation from the source repository.
+Please consult the [PyPA User Guide] to learn more about managing Pip versions.
 
 ```bash
 pip3 install git+https://github.com/ansible/ansible-lint.git