Merge branch 'devel' into faq-update-section-running-on-zos

Author: ketankelkar

.github/workflows/pip-compile-docs.yml

@@ -30,7 +30,6 @@ jobs:
       nox-args: >-
         -e
         'pip-compile(requirements)'
-        'pip-compile(requirements-relaxed)'
       reset-branch: "${{ inputs.reset-branch || false }}"
       labels: "${{ inputs.labels || 'doc builds,no_backport' }}"
       python-versions: "3.11"

docs/docsite/rst/community/documentation_contributions.rst

@@ -113,7 +113,6 @@ For more information on minimum Python versions, see the :ref:`support matrix <s
 
     pip install -r tests/requirements.in -c tests/requirements.txt # Installs tested dependency versions.
     pip install -r tests/requirements.in # Installs the unpinned dependency versions.
-    pip install -r tests/requirements-relaxed.in # Installs the unpinned dependency versions including untested antsibull-docs.
 
 
 .. note::

docs/docsite/rst/community/how_can_I_help.rst

@@ -70,6 +70,8 @@ You can also get started with solving GitHub issues labeled with the ``easyfix``
 When you choose an issue to work on, add a comment directly on the GitHub issue to say you are looking at it and let others know to avoid conflicting work. 
 You can also ask for help in a comment if you need it.
 
+For collections, refer to the :ref:`collection_quickstart` page to learn how to quickly set up your local environment, test your changes, and submit a ready-for-review pull request.
+
 Another good way to help is to review pull requests that other Ansible users have submitted. Ansible Core keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternatively, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection.
 
 Become a collection maintainer

docs/docsite/rst/installation_guide/intro_installation.rst

@@ -117,6 +117,13 @@ Include the ``--include-apps`` option to make apps in the additional python depe
 
     $ pipx inject --include-apps ansible argcomplete
 
+If you need to install dependencies from a requirements file, for example when installing the Azure collection, you can use ``runpip``.
+
+.. code-block:: console
+
+    $ pipx runpip ansible install -r ~/.ansible/collections/ansible_collections/azure/azcollection/requirements.txt
+
+
 Installing and upgrading Ansible with pip
 =========================================
 

docs/docsite/rst/porting_guides/porting_guide_11.rst

@@ -97,6 +97,109 @@ Networking
 
 No notable changes
 
+Porting Guide for v11.2.0
+=========================
+
+Known Issues
+------------
+
+dellemc.openmanage
+~~~~~~~~~~~~~~~~~~
+
+- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy.
+- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8.
+- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified.
+
+Major Changes
+-------------
+
+community.general
+~~~~~~~~~~~~~~~~~
+
+- keycloak_* modules - ``refresh_token`` parameter added. When multiple authentication parameters are provided (``token``, ``refresh_token``, and ``auth_username``/``auth_password``), modules will now automatically retry requests upon authentication errors (401), using in order the token, refresh token, and username/password (https://github.com/ansible-collections/community.general/pull/9494).
+
+community.vmware
+~~~~~~~~~~~~~~~~
+
+- vmware_dvswitch_pvlans - The VLAN ID type has been updated to be handled as an integer (https://github.com/ansible-collections/community.vmware/pull/2267).
+
+dellemc.openmanage
+~~~~~~~~~~~~~~~~~~
+
+- omevv_firmware - This module allows to update firmware of the single host and single cluster.
+
+fortinet.fortios
+~~~~~~~~~~~~~~~~
+
+- Support check_mode on all the configuration modules.
+
+google.cloud
+~~~~~~~~~~~~
+
+- google_cloud_ops_agents - role submodule removed because it prevents the collection from passing sanity and lint tests
+
+grafana.grafana
+~~~~~~~~~~~~~~~
+
+- Ability to set custom directory path for *.alloy config files by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/294
+- Fix 'dict object' has no attribute 'path' when running with --check by @JMLX42 in https://github.com/grafana/grafana-ansible-collection/pull/283
+- Update grafana template by @santilococo in https://github.com/grafana/grafana-ansible-collection/pull/300
+- add loki bloom support by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/298
+- grafana.ini yaml syntax by @intermittentnrg in https://github.com/grafana/grafana-ansible-collection/pull/232
+
+Deprecated Features
+-------------------
+
+- The ``cisco.asa`` collection has been deprecated.
+  It will be removed from Ansible 12 if no one starts maintaining it again before Ansible 12.
+  See `Collections Removal Process for unmaintained collections <https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections>`__ for more details (`https://forum.ansible.com/t/38960 <https://forum.ansible.com/t/38960>`__).
+
+amazon.aws
+~~~~~~~~~~
+
+- autoscaling_group - the ``decrement_desired_capacity`` parameter has been deprecated and will be removed in release 14.0.0 of this collection. Management of instances attached an autoscaling group can be performed using the  ``amazon.aws.autoscaling_instance`` module (https://github.com/ansible-collections/amazon.aws/pull/2396).
+- autoscaling_group - the ``replace_batch_size``, ``lc_check`` and ``lt_check`` parameters have been deprecated and will be removed in release 14.0.0 of this collection. Rolling replacement of instances in an autoscaling group can be performed using the  ``amazon.aws.autoscaling_instance_refresh`` module (https://github.com/ansible-collections/amazon.aws/pull/2396).
+- autoscaling_group - the functionality provided through the ``detach_instances`` parameter has been deprecated and will be removed in release 14.0.0 of this collection. Management of instances attached an autoscaling group can be performed using the  ``amazon.aws.autoscaling_instance`` module (https://github.com/ansible-collections/amazon.aws/pull/2396).
+- autoscaling_group - the functionality provided through the ``replace_all_instances`` parameter has been deprecated and will be removed in release 14.0.0 of this collection. Rolling replacement of instances in an autoscaling group can be performed using the  ``amazon.aws.autoscaling_instance_refresh`` module (https://github.com/ansible-collections/amazon.aws/pull/2396).
+- autoscaling_group - the functionality provided through the ``replace_instances`` parameter has been deprecated and will be removed in release 14.0.0 of this collection. Management of instances attached an autoscaling group can be performed using the  ``amazon.aws.autoscaling_instance`` module (https://github.com/ansible-collections/amazon.aws/pull/2396).
+
+community.crypto
+~~~~~~~~~~~~~~~~
+
+- Support for ansible-core 2.11, 2.12, 2.13, 2.14, 2.15, and 2.16 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with some of these versions afterwards, but we will no longer keep compatibility code that was needed to support them. Note that this means that support for all Python versions before 3.7 will be dropped, also on the target side (https://github.com/ansible-collections/community.crypto/issues/559, https://github.com/ansible-collections/community.crypto/pull/839).
+- Support for cryptography < 3.4 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with older versions of cryptography, but we will no longer keep compatibility code that was needed to support them (https://github.com/ansible-collections/community.crypto/issues/559, https://github.com/ansible-collections/community.crypto/pull/839).
+- openssl_pkcs12 - the PyOpenSSL based backend is deprecated and will be removed from community.crypto 3.0.0. From that point on you need cryptography 3.0 or newer to use this module (https://github.com/ansible-collections/community.crypto/issues/667, https://github.com/ansible-collections/community.crypto/pull/831).
+
+community.general
+~~~~~~~~~~~~~~~~~
+
+- MH module utils - attribute ``debug`` definition in subclasses of MH is now deprecated, as that name will become a delegation to ``AnsibleModule`` in community.general 12.0.0, and any such attribute will be overridden by that delegation in that version (https://github.com/ansible-collections/community.general/pull/9577).
+- atomic_container - module is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+- atomic_host - module is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+- atomic_image - module is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+- facter - module is deprecated and will be removed in community.general 12.0.0, use ``community.general.facter_facts`` instead (https://github.com/ansible-collections/community.general/pull/9451).
+- locale_gen - ``ubuntu_mode=True``, or ``mechanism=ubuntu_legacy`` is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9238).
+- proxmox - removes default value ``false`` of ``update`` parameter. This will be changed to a default of ``true`` in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9225).
+- pure module utils - the module utils is deprecated and will be removed from community.general 12.0.0. The modules using this were removed in community.general 3.0.0 (https://github.com/ansible-collections/community.general/pull/9432).
+- purestorage doc fragments - the doc fragment is deprecated and will be removed from community.general 12.0.0. The modules using this were removed in community.general 3.0.0 (https://github.com/ansible-collections/community.general/pull/9432).
+- sensu_check - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_client - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_handler - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_silence - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_subscription - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- slack - the default value ``auto`` of the ``prepend_hash`` option is deprecated and will change to ``never`` in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/9443).
+- yaml callback plugin - deprecate plugin in favor of ``result_format=yaml`` in plugin ``ansible.bulitin.default`` (https://github.com/ansible-collections/community.general/pull/9456).
+
+community.hrobot
+~~~~~~~~~~~~~~~~
+
+- boot - the various ``arch`` suboptions have been deprecated and will be removed from community.hrobot 3.0.0 (https://github.com/ansible-collections/community.hrobot/pull/134).
+
+community.vmware
+~~~~~~~~~~~~~~~~
+
+- vmware_cluster_info - the module has been deprecated and will be removed in community.vmware 7.0.0 (https://github.com/ansible-collections/community.vmware/pull/2260).
+
 Porting Guide for v11.1.0
 =========================
 
@@ -408,6 +511,7 @@ fortinet.fortios
 - Add a sanity_test.yaml file to trigger CI tests in GitHub.
 - Improve the logic for SET function to send GET request first then PUT or POST
 - Mantis
+- Remove Tokens from URLs for Improved Security
 - Support Ansible-core 2.17.
 - Support new FOS versions 7.4.4.
 - Support new FOS versions 7.6.0.
@@ -479,6 +583,8 @@ Removed Collections
 - openvswitch.openvswitch (previously included version: 2.1.1)
 - t_systems_mms.icinga_director (previously included version: 2.0.1)
 
+You can still install a removed collection manually with ``ansible-galaxy collection install <name-of-collection>``.
+
 Removed Features
 ----------------
 
@@ -569,9 +675,11 @@ Deprecated Features
 - The google.cloud collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements.
   The collection has \ `unresolved sanity test failures <https://github.com/ansible-collections/google.cloud/issues/613>`__.
   See `Collections Removal Process for collections not satisfying the collection requirements <https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#collections-not-satisfying-the-collection-requirements>`__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/8609 <https://forum.ansible.com/t/8609>`__).
+  After removal, users can still install this collection with ``ansible-galaxy collection install google.cloud``.
 - The sensu.sensu_go collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements.
   The collection has \ `unresolved sanity test failures <https://github.com/sensu/sensu-go-ansible/issues/362>`__.
   See `Collections Removal Process for collections not satisfying the collection requirements <https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#collections-not-satisfying-the-collection-requirements>`__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/8380 <https://forum.ansible.com/t/8380>`__).
+  After removal, users can still install this collection with ``ansible-galaxy collection install sensu.sensu_go``.
 
 Ansible-core
 ~~~~~~~~~~~~

noxfile.py

@@ -3,7 +3,6 @@
 import os
 import shlex
 import shutil
-from argparse import ArgumentParser, BooleanOptionalAction
 from contextlib import suppress
 from glob import iglob
 from pathlib import Path
@@ -225,20 +224,6 @@ def _clone_core_check(session: nox.Session) -> None:
     session.run("python", "docs/bin/clone-core.py", "--check")
 
 
-def _relaxed_parser(session: nox.Session) -> ArgumentParser:
-    """
-    Generate an argument parser with a --relaxed option.
-    """
-    parser = ArgumentParser(prog=f"nox -e {session.name} --")
-    parser.add_argument(
-        "--relaxed",
-        default=False,
-        action=BooleanOptionalAction,
-        help="Whether to use requirements-relaxed file. (Default: %(default)s)",
-    )
-    return parser
-
-
 def _env_python(session: nox.Session) -> str:
     """
     Get the full path to an environment's python executable
@@ -256,9 +241,8 @@ def checkers(session: nox.Session, test: str):
     """
     Run docs build checkers
     """
-    args = _relaxed_parser(session).parse_args(session.posargs)
 
-    install(session, req="requirements-relaxed" if args.relaxed else "requirements")
+    install(session, req="requirements")
     _clone_core_check(session)
     session.run("make", "-C", "docs/docsite", "clean", external=True)
     session.run("python", "tests/checkers.py", test)
@@ -269,19 +253,18 @@ def make(session: nox.Session):
     """
     Generate HTML from documentation source using the Makefile
     """
-    parser = _relaxed_parser(session)
-    parser.add_argument(
-        "make_args", nargs="*", help="Specify make targets as arguments"
-    )
-    args = parser.parse_args(session.posargs)
+    make_args = session.posargs or ["clean", "coredocs"]
 
-    install(session, req="requirements-relaxed" if args.relaxed else "requirements")
+    install(session, req="requirements")
     _clone_core_check(session)
-    make_args: list[str] = [
+    session.run(
+        "make",
+        "-C",
+        "docs/docsite",
         f"PYTHON={_env_python(session)}",
-        *(args.make_args or ("clean", "coredocs")),
-    ]
-    session.run("make", "-C", "docs/docsite", *make_args, external=True)
+        *make_args,
+        external=True,
+    )
 
 
 @nox.session

tests/checkers.py

@@ -7,6 +7,7 @@
 import json
 import os
 import pathlib
+import re
 import subprocess
 import sys
 
@@ -44,13 +45,24 @@ def run_test(name: str) -> bool:
     paths = []
     extensions = set(config.get('extensions', []))
 
+    ignore_regexs = [
+        re.compile(regex)
+        for regex in config.get('ignore_regexs', [])
+    ]
+
     for root, dir_names, file_names in os.walk(ROOT / 'docs'):
         for file_name in file_names:
             path = os.path.join(root, file_name)
             ext = os.path.splitext(path)[1]
 
-            if ext in extensions:
-                paths.append(path)
+            rel_path = os.path.relpath(path, ROOT)
+            if any(regex.match(rel_path) for regex in ignore_regexs):
+                continue
+
+            if ext not in extensions:
+                continue
+
+            paths.append(path)
 
     cmd = [sys.executable, checker_path] + paths
 

tests/checkers/rstcheck.json

@@ -1,5 +1,8 @@
 {
     "extensions": [
         ".rst"
+    ],
+    "ignore_regexs": [
+        "^docs/docsite/rst/porting_guides/porting_guide_[0-9]+\\.rst$"
     ]
 }

tests/constraints-base.in

@@ -1,5 +1,12 @@
 # This constraints file contains pins for the stable, tested versions of sphinx
 # and antsibull-docs that production builds rely upon.
+# This constraint file also pins other versions for which there are known limitations.
 
 sphinx == 7.2.5
-antsibull-docs == 2.16.2  # currently approved version
+antsibull-docs == 2.16.3  # currently approved version
+
+sphinx-rtd-theme >= 2.0.0  # Fix 404 pages with new sphinx -- https://github.com/ansible/ansible-documentation/issues/678
+rstcheck < 6  # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3
+jinja2 >= 3.0.0  # https://github.com/ansible/ansible/blob/devel/requirements.txt
+pyyaml >= 5.1  # https://github.com/ansible/ansible/blob/devel/requirements.txt
+resolvelib >= 0.5.3, < 1.1.0  # https://github.com/ansible/ansible/blob/devel/requirements.txt