[stable-2.8] Bump erlang ping to 1:20.3.8.18-1

(cherry picked from commit 4b00141)

Co-authored-by: Matt Martz <matt@sivel.net>

changelogs/.changes.yaml

@@ -1,4 +1,10 @@
 releases:
+  2.8.0:
+    codename: How Many More Times
+    fragments:
+    - 44811-xml-insertbefore-and-insertafter-parameters.yaml
+    - v2.8.0_summary.yaml
+    release_date: '2019-05-16'
   2.8.0a1:
     codename: How Many More Times
     fragments:
@@ -572,7 +578,6 @@ releases:
     - win_copy-empty-dir.yaml
     - win_copy-paths.yaml
     - win_domain-cred.yaml
-    - win_domain_membership-replace.yaml
     - win_dsc-validation.yaml
     - win_dsc-warning.yaml
     - win_file-hidden.yaml
@@ -1409,3 +1414,125 @@ releases:
       shell:
       - cmd
     release_date: '2019-04-04'
+  2.8.0b1:
+    codename: How Many More Times
+    fragments:
+    - 40366-modify-existing-volume.yml
+    - 45355-mysql_user-fix-versions-compatibilities.yml
+    - 49039-facts-xen-paravirt-cpuinfo.yaml
+    - 54494-ec2-user-data.yaml
+    - 54517-include-partition-table-postgresql-privs.yaml
+    - 54633-openssl_pkcs12_idempotency_fixes.yaml
+    - 54690-openssl_certificate-assertonly.yml
+    - 54692-ec2_asg_fix_reading_properties.yml
+    - 54799-ufw-default-direction.yml
+    - 54974-rename-safeconfigparser-to-configparser.yaml
+    - 55006-setup-is_chroot-btrfs.yaml
+    - 55038-rename-results-key-vmware-guest.yml
+    - 55083-univention-diff-UnboundLocalError.yaml
+    - dnf-4.2.2-module-remove.yaml
+    - facts-pkg-mgr-rhel.yaml
+    - fibre_channel_wwn_fact_aix.yaml
+    - fix_cache_assumption.yml
+    - gcp-compute-add-image.yaml
+    - include-no-swallow-error.yaml
+    - jinja2_nested_undefined_getitem.yaml
+    - paramiko-optional.yaml
+    - redhat_subscription_use_strings_for_yum_plugin_configs.yaml
+    - tower_job_launch-options.yaml
+    - use-module_utils-six-in-contrib-inventory.yaml
+    - user-read-passwd-when-local.yaml
+    - v2.8.0b1_summary.yaml
+    - yum-select-version.yml
+    modules:
+    - azure_rm_devtestlabcustomimage_facts
+    - azure_rm_devtestlabenvironment_facts
+    - azure_rm_devtestlabpolicy_facts
+    - azure_rm_devtestlabschedule_facts
+    - azure_rm_hdinsightcluster_facts
+    - azure_rm_virtualnetworkgateway
+    - cloudscale_server_group
+    - docker_swarm_service_info
+    - keycloak_group
+    - oci_vcn
+    - onyx_buffer_pool
+    - onyx_vxlan
+    - openssl_certificate_info
+    - openssl_csr_info
+    - openssl_privatekey_info
+    - ovirt_role
+    - podman_image
+    - podman_image_info
+    - postgresql_owner
+    - postgresql_slot
+    - vexata_volume
+    - win_format
+    - win_http_proxy
+    - win_inet_proxy
+    - xfs_quota
+    plugins:
+      connection:
+      - vmware_tools
+      inventory:
+      - cloudscale
+      - kubevirt
+    release_date: '2019-04-15'
+  2.8.0rc1:
+    codename: How Many More Times
+    fragments:
+    - 49904-rds_instance-datatype.yml
+    - 54955-docker_container-log_options-strings.yml
+    - 55078-redfish_utils_fix_406_not_acceptable_issue_with_some_oob_controllers.yml
+    - 55142-openssl_csr-crypto-backend-san.yml
+    - 55203-fix-for-removing-subscription-id-from-facts.yaml
+    - 55258-docker_host_info-old-docker-py.yml
+    - 55258-docker_swarm_service_info-old-docker-py.yml
+    - 55266-purefa_facts_remove_line.yaml
+    - 55278-cryto-use-bundled-ipaddress.yml
+    - 55384-netconf-import.yaml
+    - 55546-fixed-replacing-lb-with-ag-in-vmss.yaml
+    - 55591-docker_swarm_service-fix-uid-gid-secrets-config-type.yaml
+    - 55619-vultr_server_idempotency.yml
+    - 55681-azure_rm_manageddisk.yaml
+    - 55688-azure_rm_resourcegroup.yml
+    - 55693-fixing-final-function-app-properties.yml
+    - allow_inv_plugin_loading.yml
+    - ensure_discovery_unsafe.yml
+    - ensure_facts_safe.yml
+    - gitlab-deprecated-version.yaml
+    - k8s-fix_wait_for_response.yaml
+    - meraki_content_filtering-redundant-calls.yml
+    - meraki_static_route_api_calls.yml
+    - meraki_vlan_api_calls.yml
+    - persistent_loading.yml
+    - postgresql_idx-remove-useless-lines.yml
+    - postgresql_slot-fix-sslrootcert.yml
+    - psrp-fetch.yaml
+    - psrp-output.yaml
+    - tower_job_wait-wrong_examples.yml
+    - user-aix-shadow-file-parsing.yaml
+    - v2.8.0rc1_summary.yaml
+    - vmware_portgroup_list_host.yml
+    - vmware_tools_fix_urllib3_import.yaml
+    - vsphere_guest-corrected-state-operations.yml
+    - win_domain-setup.yaml
+    - win_reboot-psrp-command.yaml
+    - win_region-format.yaml
+    release_date: '2019-04-25'
+  2.8.0rc2:
+    codename: How Many More Times
+    fragments:
+    - 55515-use-active-state-for-any_errors_fatal.yaml
+    - bad_empty_play.yml
+    - ps-basic-json.yaml
+    - v2.8.0rc2_summary.yaml
+    release_date: '2019-05-01'
+  2.8.0rc3:
+    codename: How Many More Times
+    fragments:
+    - 51825-vmware_deploy_ovf-add_folder_doc.yml
+    - 56145-ios-net_get-net_put-update.yaml
+    - networkos_config_src_option_fix.yaml
+    - v2.8.0rc3_summary.yaml
+    - vmware_check_ssl_cert.yaml
+    release_date: '2019-05-10'

changelogs/CHANGELOG-v2.8.rst

@@ -5,13 +5,13 @@ Ansible 2.8 "How Many More Times" Release Notes
 .. contents:: Topics
 
 
-v2.8.0a1
-========
+v2.8.0
+======
 
 Release Summary
 ---------------
 
-| Release Date: 2019-04-04
+| Release Date: 2019-05-16
 | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
 
 
@@ -40,9 +40,11 @@ Minor Changes
 - Add stats on rescued/ignored tasks to play recap (https://github.com/ansible/ansible/pull/48418)
 - Add support for hex color values in Slack module.
 - Add support for per_host:no stats for the callback plugin **json** (https://github.com/ansible/ansible/pull/43123)
+- Add variable type for performance_insights_retention_period (https://github.com/ansible/ansible/issues/49904).
 - Add warning about falling back to jinja2_native=false when Jinja2 version is lower than 2.10.
 - Added Ansible.Basic C# util that contains a module wrapper and handles common functions like argument parsing and module return. This is gives the user more visibility over what the module has run and aligns PowerShell modules more closely to how Python modules are defined.
 - Added check for assert module for msg and failed_msg as a list or string types.
+- Added documentation about the folder parameter with examples in vmware_deploy_ovf (https://github.com/ansible/ansible/issues/51825).
 - Added documentation about using VMware dynamic inventory plugin.
 - Added experimental support for connecting to Windows hosts over SSH using ``ansible_shell_type=cmd`` or ``ansible_shell_type=powershell``
 - Added missing deprecation warning for param 'reboot' and use without param 'name' to the cron module.
@@ -64,6 +66,7 @@ Minor Changes
 - Drop the use of pkg_resources.  Importing pkg_resources was the costliest part of startup time for Ansible.  pkg_resources was used so that platforms with old versions of PyCrypto and Jinja2 could use parallel installed, updated versions.  Since we no longer support Python-2.6 on the controller side, we no longer have to support parallel installation to work around those old stacks.
 - Embed an overridable static sanitization method into base inventory plugin class to allow individual plugins to optionally override Add override implementation to inital set of cloud plugins
 - Ensures 'elapsed' is always returned, when timed out or failed
+- Fix API call to _wait_for_response in k8s modules (https://github.com/ansible/ansible/pull/53937).
 - Fix documentation of match test. Match requires zero or more characters at beginning of the string.
 - Fixed bug around populating host_ip in hostvars in vmware_vm_inventory.
 - Gather NVMe NQN fact (https://github.com/ansible/ansible/pull/50164)
@@ -76,7 +79,7 @@ Minor Changes
 - On Solaris, the `ansible_product_name` fact is populated for a wider range of older hardware models, and `ansible_system_vendor` fact is populated for certain known vendors.
 - Parsing plugin filter may raise TypeError, gracefully handle this exception and let user know about the syntax error in plugin filter file.
 - Python-3.8 removes platform.dist() from the standard library. To maintain compatibility we've switched to an alternative library, nir0s/distro, to detect the distribution for fact gathering.  Distributions facts may change slightly as nir0s/distro has bugfixes which the standard library's platform.dist() has lacked.
-- Raise AnsibleConnectionError on winrm connnection errors
+- Raise AnsibleConnectionError on winrm connection errors
 - Refactored the CLI code to parse the CLI arguments and then save them into a non-mutatable global singleton.  This should make it easier to modify.
 - Removed the private ``_options`` attribute of ``CallbackBase``.  See the porting guide if you need access to the command line arguments in a callback plugin.
 - Support for Cumulus Linux 2.5.4 and 3.7.3 added in setup facts (https://github.com/ansible/ansible/pull/52309).
@@ -85,6 +88,7 @@ Minor Changes
 - The ``docker_image_facts`` module has been renamed to ``docker_image_info``.
 - The ``docker_service`` module has been renamed to ``docker_compose``.
 - The restart/idempotency behavior of docker_container can now be controlled with the new comparisons parameter.
+- Try to use bundled urllib3 first, then falls back to non-bundled version in vmware_tools (https://github.com/ansible/ansible/pull/55187).
 - Update docs and return section of vmware_host_service_facts module.
 - Updated Ansible version help message in help section.
 - Updated VMware Update tag API as new specifications (https://github.com/ansible/ansible/issues/53060).
@@ -102,11 +106,13 @@ Minor Changes
 - add option to azure_rm inventory plugin which will allow the legacy script host names to be used
 - add option to shell/command to control stripping of empty lines at end of outputs
 - add parameter to checkpoint_object_facts to filter out by object type
+- add support for extending volumes in os_volume, also add module support for check_mode and diff
 - add toggle to allow user to override invalid group character filter
 - added 'unsafe' keyword to vars_prompt so users can signal 'template unsafe' content
 - adds launch type to ecs task to support fargate launch type.
 - allow user to force install a role and it's dependencies
 - allow user to force verbose messages to stderr
+- ansible facts properly detect xen paravirt vs hvm
 - ansible-galaxy: properly warn when git isn't found in an installed bin path instead of traceback
 - ansible.vars.unsafe_proxy - Removed deprecated file (https://github.com/ansible/ansible/issues/45040)
 - assert - added ``quiet`` option to the ``assert`` module to avoid verbose output (https://github.com/ansible/ansible/issues/27124).
@@ -157,7 +163,7 @@ Minor Changes
 - docker_image - the deprecated settings ``state: build`` and ``use_tls`` now display warnings when being used. They will be removed in Ansible 2.11.
 - docker_image_facts - Allow to use image ID instead of image name.
 - docker_network - Add support for IPv6 networks.
-- docker_network - Minimum docker API version explcitly set to ``1.22``.
+- docker_network - Minimum docker API version explicitly set to ``1.22``.
 - docker_network - Minimum docker server version increased from ``1.9.0`` to ``1.10.0``.
 - docker_network - Minimum docker-py version increased from ``1.8.0`` to ``1.10.0``.
 - docker_network - ``attachable`` is now used to set the ``Attachable`` property of the docker network during creation.
@@ -206,6 +212,8 @@ Minor Changes
 - fetch - Removed deprecated validate_md5 alias (https://github.com/ansible/ansible/issues/45039)
 - fix yum and dnf autoremove input sanitization to properly warn user if invalid options passed and update documentation to match
 - gather Fibre Channel WWNs fact (https://github.com/ansible/ansible/pull/37043)
+- gather Fibre Channel WWNs fact on AIX (extends https://github.com/ansible/ansible/pull/37043)
+- gcp_compute - add the image field to map to disk source iamges in the configured zones bringing it in line with old gce inventory script data
 - hashi_vault lookup plugin now supports username and password method for the authentication (https://github.com/ansible/ansible/issues/38878).
 - identity - Added support for GSSAPI authentication for the FreeIPA modules. This is enabled by either using the KRB5CCNAME or the KRB5_CLIENT_KTNAME environment variables when calling the ansible playbook. Note that to enable this feature, one has to install the urllib_gssapi python library.
 - include better error handling for Windows errors to help with debugging module errors
@@ -220,6 +228,7 @@ Minor Changes
 - jenkins_plugin - Set new default value for the update_url parameter (https://github.com/ansible/ansible/issues/52086)
 - jinja2 - Add ``now()`` function for getting the current time
 - jinja2 - accesses to attributes on an undefined value now return further undefined values rather than throwing an exception
+- jinja2 - accesses to keys/indices on an undefined value now return further undefined values rather than throwing an exception
 - junit callback plug-in - introduce a new option to consider a task only as test case if it has this value as prefix.
 - junit callback plug-in - introduce a new option to hide task arguments similar to no_log.
 - k8s - add ability to wait for some kinds of Kubernetes resources to be in the desired state
@@ -230,8 +239,8 @@ Minor Changes
 - loop_control - Add new ``extended`` option to return extended loop information (https://github.com/ansible/ansible/pull/42134)
 - loop_control's pause now allows for fractions of a second
 - macports - add upgrade parameter and replace update_ports parameter with selfupdate (https://github.com/ansible/ansible/pull/45049)
-- magic variabels - added a new ``ansible_play_role_names`` magic variable to mimic the old functionality of ``role_names``. This variable only lists the names of roles being applied to the host directly, and does not include those added via dependencies
 - magic variables - added a new ``ansible_dependent_role_names`` magic variable to contain the names of roles applied to the host indirectly, via dependencies.
+- magic variables - added a new ``ansible_play_role_names`` magic variable to mimic the old functionality of ``role_names``. This variable only lists the names of roles being applied to the host directly, and does not include those added via dependencies
 - magic variables - added a new ``ansible_role_names`` magic variable to include the names of roles being applied to the host both directly and indirectly (via dependencies).
 - mattstuff filter - fix py3 scope for unique filter errors
 - meraki_device - Add support for attaching notes to a device.
@@ -246,10 +255,12 @@ Minor Changes
 - openssl_certificate - add ``backup`` option.
 - openssl_certificate - change default value for ``acme_chain`` from ``yes`` to ``no``. Current versions of `acme-tiny <https://github.com/diafygi/acme-tiny/>`_ do not support the ``--chain`` command anymore. This default setting caused the module not to work with such versions of acme-tiny until ``acme_chain: no`` was explicitly set.
 - openssl_certificate - now works with both PyOpenSSL and cryptography Python libraries. Autodetection can be overridden with ``select_crypto_backend`` option.
+- openssl_certificate - the messages of the ``assertonly`` provider with respect to private key and CSR checking are now more precise.
 - openssl_csr - add ``backup`` option.
 - openssl_csr - add ``useCommonNameForSAN`` option which allows to disable using the common name as a SAN if no SAN is specified.
 - openssl_csr - now works with both PyOpenSSL and cryptography Python libraries. Autodetection can be overridden with ``select_crypto_backend`` option.
 - openssl_dhparam - add ``backup`` option.
+- openssl_pkcs12 - Fixed idempotency checks, the module will regenerate the pkcs12 file if any of the parameters differ from the ones in the file. The ``ca_certificates`` parameter has been renamed to ``other_certificates``. 
 - openssl_pkcs12 - add ``backup`` option.
 - openssl_pkcs12, openssl_privatekey, openssl_publickey - These modules no longer delete the output file before starting to regenerate the output, or when generating the output failed.
 - openssl_privatekey - add ``backup`` option.
@@ -258,6 +269,7 @@ Minor Changes
 - os_server_facts - added all_projects option to gather server facts from all available projects
 - package_facts, now supports multiple package managers per system. New systems supported include Gentoo's portage with portage-utils installed, as well as FreeBSD's pkg
 - pamd: remove description from RETURN values as it is unnecessary
+- paramiko is now optional.  There is no compat package on certain platforms to worry about.
 - postgres_privs now accepts 'ALL_IN_SCHEMA' objs for 'function' type (https://github.com/ansible/ansible/pull/35331).
 - postgresql_db - Added paramter conn_limit to limit the number of concurrent connection to a certain database
 - postgresql_privs - add fail_on_role parameter to control the behavior (fail or warn) when target role does not exist.
@@ -272,6 +284,7 @@ This distinction is necessary because escaping non-special chars such as
 by using regex_escape on strings being passed as a Basic Regular
 Expression.
 
+- rename safeConfigParser to ConfigParser to suppress DeprecationWarning (The SafeConfigParser class has been renamed to ConfigParser in Python 3.2.)
 - renamed `dellemc_idrac_firmware` module to `idrac_firmware`
 - retry_files_enabled now defaults to False instead of True.
 - run_command - Add a new keyword argument expand_user_and_vars, which defaults to True, allowing the module author to decide whether or paths and variables are expanded before running the command when use_unsafe_shell=False (https://github.com/ansible/ansible/issues/45418)
@@ -291,12 +304,13 @@ Expression.
 - ufw - new ``insert_relative_to`` option allows to specify rule insertion position relative to first/last IPv4/IPv6 address.
 - ufw - type of option ``insert`` is now enforced to be ``int``.
 - uri/urls - Support unix domain sockets (https://github.com/ansible/ansible/pull/43560)
+- use ansible.module_utils.six for all scripts in contrib/inventory
 - vmware_deploy_ovf - Add support for 'inject_ovf_env' for injecting user input properties in OVF environment.
+- vmware_portgroup accepts list of ESXi hostsystem. Modified get_all_host_objs API to accept list of hostsystems.
 - when showing defaults for CLI options in manpage/docs/--help avoid converting paths
 - win_chocolatey - Added the ability to pin a package using the ``pinned`` option - https://github.com/ansible/ansible/issues/38526
 - win_chocolatey - added the allow_multiple module option to allow side by side installs of the same package
 - win_chocolatey - support bootstrapping Chocolatey from other URLs with any PS script that ends with ``.ps1``, originally this script had to be ``install.ps1``
-- win_domain_membership - will now fail if an existing AD object for the host exists and ``allow_existing_computer_account=no`` - https://github.com/ansible/ansible/pull/53542
 - win_dsc - Display the warnings produced by the DSC engine for better troubleshooting - https://github.com/ansible/ansible/issues/51543
 - win_dsc - The Verbose logs will be returned when running with ``-vvv``.
 - win_dsc - The module invocation and possible options will be displayed when running with ``-vvv``.
@@ -321,7 +335,8 @@ Expression.
 - windows async - async directory is now controlled by the ``async_dir`` shell option and not ``remote_tmp`` to match the POSIX standard.
 - windows async - change default directory from ``$env:TEMP\.ansible_async`` to ``$env:USERPROFILE\.ansible_async`` to match the POSIX standard.
 - windows become - Add support for passwordless become.
-- windows become - Moved to shared C# util so modules can utilise the code.
+- windows become - Moved to shared C# util so modules can utilize the code.
+- xml - Introduce ``insertbefore`` and ``insertafter`` to specify the position (https://github.com/ansible/ansible/pull/44811)
 - yum - provide consistent return data structure when run in check mode and not in check mode
 - yum - when checking for updates, now properly include Obsoletes (both old and new) package data in the module JSON output, fixes https://github.com/ansible/ansible/issues/39978
 - yum and dnf can now handle installing packages from URIs that are proxy redirects and don't end in the .rpm file extension
@@ -336,13 +351,13 @@ Deprecated Features
 - Ansible-defined environment variables not starting with `ANSIBLE_` have been deprecated.  New names match the old name plus the `ANSIBLE_` prefix. These environment variables have been deprecated: LIBVIRT_LXC_NOSECLABEL, DISPLAY_SKIPPED_HOSTS, and NETWORK_GROUP_MODULES
 - async - setting the async directory using ``ANSIBLE_ASYNC_DIR`` as an environment key in a task or play is deprecated and will be removed in Ansible 2.12. Set a var name ``ansible_async_dir`` instead.
 - cache plugins - Importing cache plugins directly is deprecated and will be removed in 2.12. Cache plugins should use the cache_loader instead so cache options can be reconciled via the configuration system rather than constants.
-- docker_network - Deprecate ``ipam_options`` in favour of ``ipam_config``.
-- docker_swarm_service - Deprecate ``constraints`` in favour of ``placement``.
-- docker_swarm_service - Deprecate ``limit_cpu`` and ``limit_memory`` in favour of ``limits``.
-- docker_swarm_service - Deprecate ``log_driver`` and ``log_driver_options`` in favour of ``logging``.
-- docker_swarm_service - Deprecate ``reserve_cpu`` and ``reserve_memory`` in favour of ``reservations``.
-- docker_swarm_service - Deprecate ``restart_policy``, ``restart_policy_attempts``, ``restart_policy_delay`` and ``restart_policy_window`` in favour of ``restart_config``.
-- docker_swarm_service - Deprecate ``update_delay``, ``update_parallelism``, ``update_failure_action``, ``update_monitor``, ``update_max_failure_ratio`` and ``update_order`` in favour of ``update_config``.
+- docker_network - Deprecate ``ipam_options`` in favor of ``ipam_config``.
+- docker_swarm_service - Deprecate ``constraints`` in favor of ``placement``.
+- docker_swarm_service - Deprecate ``limit_cpu`` and ``limit_memory`` in favor of ``limits``.
+- docker_swarm_service - Deprecate ``log_driver`` and ``log_driver_options`` in favor of ``logging``.
+- docker_swarm_service - Deprecate ``reserve_cpu`` and ``reserve_memory`` in favor of ``reservations``.
+- docker_swarm_service - Deprecate ``restart_policy``, ``restart_policy_attempts``, ``restart_policy_delay`` and ``restart_policy_window`` in favor of ``restart_config``.
+- docker_swarm_service - Deprecate ``update_delay``, ``update_parallelism``, ``update_failure_action``, ``update_monitor``, ``update_max_failure_ratio`` and ``update_order`` in favor of ``update_config``.
 - inventory plugins - Inventory plugins using self.cache is deprecated and will be removed in 2.12. Inventory plugins should use self._cache as a dictionary to store results.
 - magic variables - documented the deprecation of the ``role_names`` magic variable in favor of either ``ansible_role_names`` (including dependency role names) or ``ansible_play_role_names`` (excluding dependencies).
 - win_nssm - Deprecate ``app_parameters`` option in favor of ``arguments``.
@@ -377,10 +392,13 @@ Bugfixes
 - Allow to use rundeck_acl_policy with python 2 and 3
 - Also check stdout for interpreter errors for more intelligent messages to user
 - Ansible JSON Decoder - Switch from decode to object_hook to support nested use of __ansible_vault and __ansible_unsafe (https://github.com/ansible/ansible/pull/45514)
+- Ansible.Basic - Fix issue when deserializing a JSON string that is not a dictionary - https://github.com/ansible/ansible/pull/55691
 - Attempt to avoid race condition based on incorrect buffer size assumptions
+- Be sure to use the active state when checking for any_errors_fatal
 - Correctly detect multiple ipv6 addresses per device in facts (https://github.com/ansible/ansible/issues/49473)
 - Detect FreeBSD KVM guests in facts (https://github.com/ansible/ansible/issues/49158)
 - Detect IP addresses on a system with busybox properly (https://github.com/ansible/ansible/issues/50871)
+- Enable azure manged disk test
 - Enhance the conditional check to include main.yml if it is not from 'role/vars/' (https://github.com/ansible/ansible/pull/51926).
 - Extend support for Devuan ascii distribution
 - FieldAttribute - Do not use mutable defaults, instead allow supplying a callable for defaults of mutable types (https://github.com/ansible/ansible/issues/46824)
@@ -393,7 +411,9 @@ Bugfixes
 - Fix for callback plugins on Python3 when a module returns non-string field names in its results.  (https://github.com/ansible/ansible/issues/49343)
 - Fix handlers to allow for templated values in run_once (https://github.com/ansible/ansible/issues/27237)
 - Fix how debconf handles boolean questions to accurately compare
+- Fix invalid src option return response for network config modules (https://github.com/ansible/ansible/pull/56076)
 - Fix issue getting output from failed ios commands when ``check_rc=False``
+- Fix net_get and net_put task run failure - https://github.com/ansible/ansible/pull/56145
 - Fix rabbitmq_plugin idempotence due to information message in new version of rabbitmq (https://github.com/ansible/ansible/pull/52166)
 - Fix searchpath in the template lookup to work the same way as in the template module.
 - Fix the password lookup when run from a FIPS enabled system.  FIPS forbids the use of md5 but we can use sha1 instead. https://github.com/ansible/ansible/issues/47297
@@ -404,15 +424,20 @@ Bugfixes
 - Fixed KeyError issue in vmware_host_config_manager when a supported option isn't already set (https://github.com/ansible/ansible/issues/44561).
 - Fixed an issue with ansible-doc -l failing when parsing some plugin documentation.
 - Fixed issue related to --yaml flag in vmware_vm_inventory. Also fixed caching issue in vmware_vm_inventory (https://github.com/ansible/ansible/issues/52381).
-- Give user better error messages and more information on verbose about inventory plugin behaviour
+- Fixed to handle arguments correctly even if inventory and credential variables are not specified (#25017,#37567)
+- Fixes an issue when subscription_id is masked in the output when it's passed as one of the parameters.
+- Fixes replacing load balancer with application gateway in Azure virtualmachine scaleset, as leaning up old load balancer was not done properly.
+- Give user better error messages and more information on verbose about inventory plugin behavior
 - Guard ``HTTPSClientAuthHandler`` under HTTPS checks, to avoid tracebacks when python is compiled without SSL support (https://github.com/ansible/ansible/issues/50339)
 - Handle ClientError exceptions when describing VPC peering connections.
 - Handle error paginating object versions when bucket does not exist (https://github.com/ansible/ansible/issues/49393)
 - Handle exception when there is no snapshot available in virtual machine or template while cloning using vmware_guest.
 - Hardware fact gathering now completes on Solaris 8.  Previously, it aborted with error `Argument 'args' to run_command must be list or string`.
 - If large integers are passed as options to modules under Python 2, module argument parsing will reject them as they are of type ``long`` and not of type ``int``.
+- Include partition tables in the ALL_IN_SCHEMA option for postgresql-privs (https://github.com/ansible/ansible/issues/54516)
 - Last loaded handler with the same name is used
 - Meraki - Lookups using org_name or net_name no longer query Meraki twice, only once. Major performance improvements.
+- Move netconf import errors from import to use.
 - Narrow the cases in which we warn about Jinja2 unique filters https://github.com/ansible/ansible/issues/46189
 - Now be specific about the entry that trips an error
 - PLUGIN_FILTERS_CFG - Ensure that the value is treated as type=path, and that we use the standard section of ``defaults`` instead of ``default`` (https://github.com/ansible/ansible/pull/45994)
@@ -421,7 +446,9 @@ Bugfixes
 - Restore SIGPIPE to SIG_DFL when creating subprocesses to avoid it being ignored under Python 2.
 - Restore timeout in set_vm_power_state operation in vmware_guest_powerstate module.
 - Retry deleting the autoscaling group if there are scaling activities in progress.
+- SECURITY Fixed the python interpreter detection, added in 2.8.0alpha1, to properly mark the returned data as untemplatable. This prevents a malicious managed machine from running code on the controller via templating.
 - States ``dump`` and ``restore`` only need pg_dump and pg_restore. These tools don't use psycopg2 so this change tries to avoid the use of it in these cases. Fixes https://github.com/ansible/ansible/issues/35906
+- The internal key `results` in vmware_guest_snapshot module return renamed to `snapshot_results`.
 - The patch fixing the regression of no longer preferring matching security groups in the same VPC https://github.com/ansible/ansible/pull/45787 (which was also backported to 2.6) broke EC2-Classic accounts. https://github.com/ansible/ansible/pull/46242 removes the assumption that security groups must be in a VPC.
 - This reverts some changes from commit 723daf3. If a line is found in the file, exactly or via regexp matching, it must not be added again. `insertafter`/`insertbefore` options are used only when a line is to be inserted, to specify where it must be added.
 - Use custom JSON encoder in conneciton.py so that ansible objects (AnsibleVaultEncryptedUnicode, for example) can be sent to the persistent connection process
@@ -431,26 +458,30 @@ Bugfixes
 - aci_interface_policy_leaf_policy_group - Support missing aep
 - aci_rest - Fix issue ignoring custom port
 - aci_switch_leaf_selector - Support empty policy_group
+- acme_certificate - use ``ipaddress`` module bundled with Ansible for normalizations needed for OpenSSL backend.
 - acme_certificate - writing result failed when no path was specified (i.e. destination in current working directory).
 - acme_challenge_cert_helper - the module no longer crashes when the required ``cryptography`` library cannot be found.
+- add resource group test
 - adhoc always added async_val and poll to tasks, but now includes are enforcing non valid parameters, this bypasses the error.
 - allow 'dict()' jinja2 global to function the same even though it has changed in jinja2 versions
+- allow loading inventory plugins adjacent to playbooks
 - allow nice error to work when auto plugin reads file w/o `plugin` field
 - allow using openstack inventory plugin w/o a cache
 - ansible-doc, --json now is 'type intelligent' and reinstated --all option
 - ansible-doc, removed local hardcoded listing, now uses the 'central' list from constants and other minor issues
 - ansible-galaxy - Prevent unicode errors when searching - https://github.com/ansible/ansible/issues/42866
-- apt - Show a warning hint in case apt auto-installs its dependecies.
+- apt - Show a warning hint in case apt auto-installs its dependencies.
 - apt_repository - do not require a tty to prevent errors parsing GPG keys (https://github.com/ansible/ansible/issues/49949)
 - assemble - avoid extra newline on Python 3 (https://github.com/ansible/ansible/issues/44739)
 - async - fixed issue where the shell option ``async_dir`` was not being used when setting the async directory.
 - async_wrapper - Allocate an explicit stdin (https://github.com/ansible/ansible/issues/50758)
-- avoid empty groups in ansbile-inventory JSON output as they will be interpreted as hosts
+- avoid empty groups in ansible-inventory JSON output as they will be interpreted as hosts
 - avoid making multiple 'sub copies' when traversing already 'clean copy' of dict
 - aws_ec2 - fixed issue where cache did not contain the computed groups
 - azure_rm inventory plugin - fix azure batch request (https://github.com/ansible/ansible/pull/50006)
 - azure_rm inventory plugin - fix runtime error under Python3 (https://github.com/ansible/ansible/pull/46608)
 - azure_rm_deployment - fixed regression that prevents resource group from being created (https://github.com/ansible/ansible/issues/45941)
+- azure_rm_functionapp - adding two properties which need to be set by default, otherwise function app won't behave correctly in Azure Portal.
 - azure_rm_managed_disk_facts - added missing implementation of listing managed disks by resource group
 - azure_rm_mysqlserver - fixed issues with passing parameters while updating existing server instance
 - azure_rm_postgresqldatabase - fix force_update bug (https://github.com/ansible/ansible/issues/50978).
@@ -472,7 +503,7 @@ Bugfixes
 - cs_iso - Add the 'is_public' param into argument_spec to allow the registering of public iso.
 - cs_network_offering - Add a choice list for supported_services parameter in arg_spec.
 - cs_template - Fixed a KeyError on state=extracted.
-- delegate_to - Fix issue where delegate_to was upplied via ``apply`` on an include, where a loop was present on the include
+- delegate_to - Fix issue where delegate_to was applied via ``apply`` on an include, where a loop was present on the include
 - delegate_to - When templating ``delegate_to`` in a loop, don't use the task for a cache, return a special cache through ``get_vars`` allowing looping over a hostvar (https://github.com/ansible/ansible/issues/47207)
 - dict2items - Allow dict2items to work with hostvars
 - disallow non dict results from module and allow user to continue using with a warning.
@@ -480,6 +511,7 @@ Bugfixes
 - dnf - allow to operate on file paths (https://github.com/ansible/ansible/issues/50843)
 - dnf - enable package name specification for absent
 - dnf - fix issue where ``conf_file`` was not being loaded properly
+- dnf - fix issue with dnf API calls to adapt to changes in upstream dnf version 4.2.2
 - dnf - fix package parsing to handle git snapshot nevra
 - dnf - fix update_cache combined with install operation to not cause dnf transaction failure
 - do not return ``state: absent`` when the module returns either ``path`` or ``dest`` but the file does not exists (https://github.com/ansible/ansible/issues/35382)
@@ -499,6 +531,7 @@ Bugfixes
 - docker_container - fix ``paused`` option (which never worked).
 - docker_container - fix behavior of ``detach: yes`` if ``auto_remove: yes`` is specified.
 - docker_container - fix idempotency check for published_ports in some special cases.
+- docker_container - fix idempotency of ``log_options`` when non-string values are used. Also warn user that this is the case.
 - docker_container - fix idempotency problems with docker-py caused by previous ``init`` idempotency fix.
 - docker_container - fix interplay of docker-py version check with argument_spec validation improvements.
 - docker_container - fixing race condition when ``detach`` and ``auto_remove`` are both ``true``.
@@ -506,6 +539,7 @@ Bugfixes
 - docker_container - refactored minimal docker-py/API version handling, and fixing such handling of some options.
 - docker_container - the behavior is improved in case ``image`` is not specified, but needed for (re-)creating the container.
 - docker_container, docker_image, docker_image_facts - also find local image when image name is prefixed with ``docker.io/library/`` or ``docker.io/``.
+- docker_host_info - ``network_filters`` needs docker-py 2.0.2, ``disk_usage`` needs docker-py 2.2.0.
 - docker_network - ``driver_options`` containing Python booleans would cause Docker to throw exceptions.
 - docker_network - now returns warnings from docker daemon on network creation.
 - docker_swarm - Fixed node_id parameter not working for node removal (https://github.com/ansible/ansible/issues/53501)
@@ -517,6 +551,7 @@ Bugfixes
 - docker_swarm - properly implement check mode (it did apply changes).
 - docker_swarm - the ``force`` option was ignored when ``state: present``.
 - docker_swarm_service - Added support for ``read_only`` parameter.
+- docker_swarm_service - Change the type of options ``gid`` and ``uid`` on ``secrets`` and ``configs`` to ``str``.
 - docker_swarm_service - Document ``labels`` and ``container_labels`` with correct type.
 - docker_swarm_service - Document ``limit_memory`` and ``reserve_memory`` correctly on how to specify sizes.
 - docker_swarm_service - Document minimal API version for ``configs`` and ``secrets``.
@@ -538,6 +573,7 @@ Bugfixes
 - docker_swarm_service - now returns warnings from docker daemon on service creation.
 - docker_swarm_service - the return value was documented as ``ansible_swarm_service``, but the module actually returned ``ansible_docker_service``. Documentation and code have been updated so that the variable is now called ``swarm_service``. In Ansible 2.7.x, the old name ``ansible_docker_service`` can still be used to access the result.
 - docker_swarm_service: fails because of default "user: root" (https://github.com/ansible/ansible/issues/49199)
+- docker_swarm_service_info - work around problems with older docker-py versions such as 2.0.2.
 - docker_volume - ``labels`` now work (and are a ``dict`` and no longer a ``list``).
 - docker_volume - fix ``force`` and change detection logic. If not both evaluated to ``True``, the volume was not recreated.
 - document debug's var already having implicit moustaches
@@ -545,7 +581,9 @@ Bugfixes
 - dynamic includes - Add missed ``run_once`` to valid include attributes (https://github.com/ansible/ansible/pull/48068)
 - dynamic includes - Use the copied and merged task for calculating task vars in the free strategy (https://github.com/ansible/ansible/issues/47024)
 - ec2 - Correctly sets the end date of the Spot Instance request. Sets `ValidUntil` value in proper way so it will be auto-canceled through `spot_wait_timeout` interval.
+- ec2 - Only use user_data if the user has specified a value. This prevents setting the instance's user data to b'None'.
 - ec2 - if the private_ip has been provided for the new network interface it shouldn't also be added to top level parameters for run_instances()
+- ec2_asg - Fix error where ASG dict has no launch config or launch template key
 - ec2_asg - Fix scenario where min_size can end up passing None type to boto
 - ec2_group - Sanitize the ingress and egress rules before operating on them by flattening any lists within lists describing the target CIDR(s) into a list of strings. Prior to Ansible 2.6 the ec2_group module accepted a list of strings, a list of lists, or a combination of strings and lists within a list. https://github.com/ansible/ansible/pull/45594
 - ec2_group - There can be multiple security groups with the same name in different VPCs. Prior to 2.6 if a target group name was provided, the group matching the name and VPC had highest precedence. Restore this behavior by updated the dictionary with the groups matching the VPC last.
@@ -553,18 +591,20 @@ Bugfixes
 - ec2_instance - Does not return ``instances`` when ``wait: false`` is specified
 - ecs_ecr and iam_role - replace uses of sort_json_policy_dict with compare_policies which is compatible with Python 3
 - elb_target_group - cast target ports to integers before making API calls after the key 'Targets' is in params.
+- ensure module results and facts are marked untrusted as templates for safer use within the same task
 - ensure we always have internal module attributes set, even if not being passed (fixes using modules as script)
 - ensure we have a XDG_RUNTIME_DIR, as it is not handled correctly by some privilege escalation configurations
 - explain 'bare variables' in error message
 - fact gathering to obey play tags
 - facts - detect VMs from google cloud engine and scaleway
+- facts - ensure that the default package manager for RHEL < 8 is yum, and dnf for newer
 - facts - properly detect package manager for a Fedora/RHEL/CentOS system that has rpm-ostree installed
 - facts - set virtualization_role for KVM hosts (https://github.com/ansible/ansible/issues/49734)
 - fetch_url did not always return lower-case header names in case of HTTP errors (https://github.com/ansible/ansible/pull/45628).
 - file - Allow state=touch on file the user does not own https://github.com/ansible/ansible/issues/50943
 - fix DNSimple to ensure check works even when the number of records is larger than 100
 - fix FactCache.update() to conform to the dict API.
-- fix ansible-pull hanlding of extra args, complex quoting is needed for inline JSON
+- fix ansible-pull handling of extra args, complex quoting is needed for inline JSON
 - fix elasticsearch_plugin force to be bool (https://github.com/ansible/ansible/pull/47134)
 - fix handling of firewalld port if protocol is missing
 - flatpak - Makes querying of present flatpak name more robust, fixes
@@ -575,6 +615,7 @@ Bugfixes
 - get_url - Don't re-download files unnecessarily when force=no (https://github.com/ansible/ansible/issues/45491)
 - get_url - Fix issue with checksum validation when using a file to ensure we skip lines in the file that do not contain exactly 2 parts. Also restrict exception handling to the minimum number of necessary lines (https://github.com/ansible/ansible/issues/48790)
 - get_url - support remote checksum files with paths specified with leading dots (`./path/to/file`)
+- gitlab modules - Update version deprecations to use strings instead of integers so that ``2.10`` isn't converted to ``2.1``. (https://github.com/ansible/ansible/pull/55395)
 - handle non strings in requirements version for ansible-galaxy
 - handle option json errors more gracefully, also document options are not vaultable.
 - handle xmlrpc errors in the correct fashion for rhn_channel
@@ -582,6 +623,7 @@ Bugfixes
 - host execution order - Fix ``reverse_inventory`` not to change the order of the items before reversing on python2 and to not backtrace on python3
 - icinga2_host - fixed the issue with not working ``use_proxy`` option of the module.
 - imports - Prevent the name of an import from being addressable as a handler, only the tasks within should be addressable. Use an include instead of an import if you need to execute many tasks from a single handler (https://github.com/ansible/ansible/issues/48936)
+- include_role - Don't swallow errors when processing included files/roles (https://github.com/ansible/ansible/issues/54786)
 - include_tasks - Ensure we give IncludedFile the same context as TaskExecutor when templating the parent include path allowing for lookups in the included file path (https://github.com/ansible/ansible/issues/49969)
 - include_tasks - Fixed an unexpected exception if no file was given to include.
 - include_vars - error handlers now generate proper error messages with non-ASCII args
@@ -590,7 +632,7 @@ Bugfixes
 - inventory plugins - Fix creating groups from composed variables by getting the latest host variables
 - inventory_aws_ec2 - fix no_log indentation so AWS temporary credentials aren't displayed in tests
 - ipaddr - fix issue where network address was blank for 0-size networks (https://github.com/ansible/ansible/issues/17872)
-- issue a warning when local fact is not correctly loaded, old behaviour just updated fact value with the error.
+- issue a warning when local fact is not correctly loaded, old behavior just updated fact value with the error.
 - jail connection - Support empty files with copying to target (https://github.com/ansible/ansible/issues/36725)
 - jenkins_plugin - Prevent plugin to be reinstalled when state=present (https://github.com/ansible/ansible/issues/43728)
 - jenkins_plugin - ``version: latest`` should install new plugins with their dependencies
@@ -610,10 +652,14 @@ Bugfixes
 - make YAML inventory more tolerant to comments/empty/None entries
 - meraki_config_template - Fix conditions which prevented code from executing when specifying net_id
 - meraki_ssid - Fix module to actually perform changes when state is present and SSID is referenced by number and not name.
+- meraki_static_route - Module would make unnecessary API calls to Meraki when ``net_id`` is specified in task.
+- meraki_static_route - Module would make unnecessary API calls to Meraki when ``net_id`` is specified in task.
+- meraki_vlan - Module would make unnecessary API calls to Meraki when net_id is specified in task.
 - modprobe - The modprobe module now detects builtin kernel modules. If a kernel module is builtin the modprobe module will now: succeed (without incorrectly reporting changed) if ``state`` is ``present``; and fail if ``state`` is ``absent`` (with an error message like ``modprobe: ERROR: Module nfs is builtin.``). (https://github.com/ansible/ansible/pull/37150)
 - mysql - MySQLdb doesn't import the cursors module for its own purposes so it has to be imported in MySQL module utilities before it can be used in dependent modules like the proxysql module family.
 - mysql - fixing unexpected keyword argument 'cursorclass' issue after migration from MySQLdb to PyMySQL.
 - mysql_*, proxysql_* - PyMySQL (a pure-Python MySQL driver) is now a preferred dependency also supporting Python 3.X.
+- mysql_user: fix compatibility issues with various MySQL/MariaDB versions
 - mysql_user: fix the working but incorrect regex used to check the user privileges.
 - mysql_user: match backticks, single and double quotes when checking user privileges.
 - now default is ``list`` so ``None`` is bad comparison for gathering
@@ -626,12 +672,15 @@ Bugfixes
 - openssl_certificate - fix ``state=absent``.
 - openssl_certificate - make sure that extensions are actually present when their values should be checked.
 - openssl_certificate, openssl_csr, openssl_pkcs12, openssl_privatekey, openssl_publickey - The modules are now able to overwrite write-protected files (https://github.com/ansible/ansible/issues/48656).
+- openssl_csr - SAN normalization for IP addresses for the pyOpenSSL backend was broken.
 - openssl_csr - fix byte encoding issue on Python 3
 - openssl_csr - fix problem with idempotency of keyUsage option.
 - openssl_csr - fixes idempotence problem with PyOpenSSL backend when no Subject Alternative Names were specified.
 - openssl_csr - improve ``subject`` validation.
 - openssl_csr - improve error messages for invalid SANs.
+- openssl_csr - the cryptography backend's idempotency checking for basic constraints was broken.
 - openssl_csr, openssl_certificate, openssl_publickey - properly validate private key passphrase; if it doesn't match, fail (and not crash or ignore).
+- openssl_csr, openssl_csr_info - use ``ipaddress`` module bundled with Ansible for normalizations needed for pyOpenSSL backend.
 - openssl_dhparam - fix ``state=absent`` idempotency and ``changed`` flag.
 - openssl_pkcs12 - No need to specify ``privatekey_path`` when ``friendly_name`` is specified.
 - openssl_pkcs12 - fix byte encoding issue on Python 3
@@ -650,10 +699,13 @@ Bugfixes
 - pamd: fix state: updated idempotence (see https://github.com/ansible/ansible/issues/47083)
 - pamd: update regex to allow leading dash and retain EOF newline (see https://github.com/ansible/ansible/issues/47418)
 - paramiko_ssh - add auth_timeout parameter to ssh.connect when supported by installed paramiko version. This will prevent "Authentication timeout" errors when a slow authentication step (>30s) happens with a host (https://github.com/ansible/ansible/issues/42596)
+- pass correct loading context to persistent connections
 - pip - idempotence in check mode now works correctly.
 - play order is now applied under all circumstances, fixes
-- postgresql_db - the module fails not always when pg_dump errors occured (https://github.com/ansible/ansible/issues/40424).
+- postgresql_db - the module fails not always when pg_dump errors occurred (https://github.com/ansible/ansible/issues/40424).
+- postgresql_idx - removed useless rows that remained after the previous refactoring
 - postgresql_privs - change fail to warn if PostgreSQL role does not exist (https://github.com/ansible/ansible/issues/46168).
+- postgresql_slot - fixed sslrootcert mapping to psycopg2 connection string
 - postgresql_user - create pretty error message when creating a user without an encrypted password on newer PostgreSQL versions
 - preserve Noneness of pwdfile when it is None in virtualbox inventory plugin
 - prevent import_role from inserting dupe into `roles:` execution when duplicate signature role already exists in the section.
@@ -663,12 +715,17 @@ Bugfixes
 - psexec - give proper error message when the psexec requirements are not installed
 - psrp - Explicitly documented the extra auth options that could have been passed in - https://github.com/ansible/ansible/issues/54664
 - psrp - Fix UTF-8 output - https://github.com/ansible/ansible/pull/46998
+- psrp - Fix blank newlines appearing before ``stdout`` when using ``script`` or ``raw`` with the ``psrp`` connection plugin
 - psrp - Fix issue when dealing with unicode values in the output for Python 2
+- psrp - Fix issues when fetching large files causing a memory leak - https://github.com/ansible/ansible/issues/55239
+- psrp - Fix issues with propagating errors back to Ansible with ``raw`` tasks
 - psrp - do not display bootstrap wrapper for each module exec run
+- purefa_facts - remove unnecessary line that could cause failure in rare circumstances.
 - purefa_facts and purefb_facts now correctly adds facts into main ansible_fact dictionary (https://github.com/ansible/ansible/pull/50349)
 - rabbitmq_binding - Delete binding when ``state`` is ``absent``.
 - random_mac - generate a proper MAC address when the provided vendor prefix is two or four characters (https://github.com/ansible/ansible/issues/50838)
 - rds_instance - Cluster_id which is an alias of db_cluster_identifier is a mandatory check target.
+- re allow empty plays for now, but add deprecation msg.
 - reboot - Fix bug where the connection timeout was not reset in the same task after rebooting
 - reboot - add appropriate commands to make the plugin work with VMware ESXi (https://github.com/ansible/ansible/issues/48425)
 - reboot - add reboot_timeout parameter to the list of parameters so it can be used.
@@ -680,8 +737,11 @@ Bugfixes
 - reboot - use IndexError instead of TypeError in exception
 - reboot - use a common set of commands for older and newer Solaris and SunOS variants (https://github.com/ansible/ansible/pull/48986)
 - reboot - use unicode instead of bytes for stdout and stderr to match the type returned from low_level_execute()
+- redfish_utils - fix "406 Not Acceptable" issue with some OOB controllers (https://github.com/ansible/ansible/issues/55078)
 - redfish_utils - fix reference to local variable 'systems_service'
+- redhat_subscription - For compatibility using the redhat_subscription module on hosts set to use a python 3 interpreter, use string values when updating yum plugin configuration files.
 - redis cache - Support version 3 of the redis python library (https://github.com/ansible/ansible/issues/49341)
+- rely on method existing vs loosely related _cache attribute, also fix data persistence issue on plugin reuse across sources.
 - remote home directory - Disallow use of remote home directories that include relative pathing by means of `..` (CVE-2019-3828) (https://github.com/ansible/ansible/pull/52133)
 - remote_management foreman - Fixed issue where it was impossible to createdelete a product because product was missing in dict choices ( https://github.com/ansible/ansible/issues/48594 )
 - remove bare var handling from conditionals (not needed since we removed bare vars from `with_` loops) to normalize handling of variable values, no matter if the string value comes from a top level variable or from a dictionary key or subkey
@@ -698,6 +758,7 @@ Bugfixes
 - s3_bucket - Prior to 2.6 using non-text tags worked, although was not idempotent. In 2.6 waiters were introduced causing non-text tags to be fatal to the module's completion. This fixes the module failure as well as idempotence using integers as tags.
 - scaleway inventory plugin - Fix response.getheaders regression (https://github.com/ansible/ansible/pull/48671)
 - script inventory plugin - Don't pass file_name to DataLoader.load, which will prevent misleading error messages (https://github.com/ansible/ansible/issues/34164)
+- setup - properly detect is_chroot on Btrfs (https://github.com/ansible/ansible/issues/55006)
 - setup - properly gather iSCSI information for AIX (https://github.com/ansible/ansible/pull/44644)
 - simple code collapse, avoid a lot of repetition
 - skip invalid plugin after warning in loader
@@ -707,11 +768,18 @@ Bugfixes
 - ssh - Properly quote the username to allow usernames containing spaces (https://github.com/ansible/ansible/issues/49968)
 - ssh connection - Support empty files with piped transfer_method (https://github.com/ansible/ansible/issues/45426)
 - ssh connection - do not retry with invalid credentials to prevent account lockout (https://github.com/ansible/ansible/issues/48422)
-- systemd - warn when exeuting in a chroot environment rather than failing (https://github.com/ansible/ansible/pull/43904)
+- systemd - warn when executing in a chroot environment rather than failing (https://github.com/ansible/ansible/pull/43904)
 - tags - allow tags to be specified by a variable (https://github.com/ansible/ansible/issues/49825)
 - templar - Do not strip new lines in native jinja - https://github.com/ansible/ansible/issues/46743
 - terraform - fixed issue where state "planned" wouldn't return an output and the project_path had to exist in two places (https://github.com/ansible/ansible/issues/39689)
+- tower_job_wait - Fixed wrong variable specification in examples
 - tweak inv plugin skip msg to be more precise, also require higher verbosity to view
+- udm_dns_record - Fix issues when state is absent with undefined variable diff at the module return.
+- udm_dns_zone - Fix issues when state is absent with undefined variable diff at the module return.
+- udm_group - Fix issues when state is absent with undefined variable diff at the module return.
+- udm_share - Fix issues when state is absent with undefined variable diff at the module return.
+- udm_user - Fix issues when state is absent with undefined variable diff at the module return.
+- ufw - when ``default`` is specified, ``direction`` does not needs to be specified. This was accidentally introduced in Ansible 2.7.8.
 - ufw: make sure that only valid values for ``direction`` are passed on.
 - unarchive - add two more error conditions to unarchive to present more accurate error message (https://github.com/ansible/ansible/issues/51848)
 - unsafe - Add special casing to sets, to support wrapping elements of sets correctly in Python 3 (https://github.com/ansible/ansible/issues/47372)
@@ -722,13 +790,19 @@ Bugfixes
 - use to_native (py2/3 safe) instead of str for 'textualizing' intput in async_status
 - user - add documentation on what underlying tools are used on each platform (https://github.com/ansible/ansible/issues/44266)
 - user - do not report changes every time when setting password_lock (https://github.com/ansible/ansible/issues/43670)
+- user - fix a bug when checking if a local user account exists on a system using directory authentication (https://github.com/ansible/ansible/issues/50947, https://github.com/ansible/ansible/issues/38206)
 - user - fixed the fallback mechanism for creating a user home directory when the directory isn't created with `useradd` command. Home directory will now have a correct mode and it won't be created in a rare situation when a local user is being deleted but it exists on a central user system (https://github.com/ansible/ansible/pull/49262).
 - user - on FreeBSD set the user expiration time as seconds since the epoch in UTC to avoid timezone issues
+- user - properly parse the shadow file on AIX (https://github.com/ansible/ansible/issues/54461)
 - user - properly remove expiration when set to a negative value (https://github.com/ansible/ansible/issues/47114)
 - user - remove warning when creating a disabled account with '!' or '*' in the password field (https://github.com/ansible/ansible/issues/46334)
 - user module - do not pass ssh_key_passphrase on cmdline (CVE-2018-16837)
 - vault - Improve error messages encountered when reading vault files (https://github.com/ansible/ansible/issues/49252)
+- vmware - The VMware modules now enable the SSL certificate check unless ``validate_certs`` is ``false``.
+- vsphere_guest - creating machines without vm_extra_config allowed
+- vsphere_guest - powering on/off absent virtual machine will fail
 - vultr - fixed the handling of an inconsistency in the response from Vultr API when it returns an unexpected empty list instead a empty dict.
+- vultr_server - Fix idempotency for options ``ipv6_enabled`` and ``private_network_enabled``.
 - vultr_server - fixed multiple ssh keys were not handled.
 - vultr_server_facts - fixed facts gathering fails if firewall is enabled.
 - win_acl - Fix issues when using paths with glob like characters, e.g. ``[``, ``]``
@@ -743,6 +817,7 @@ Bugfixes
 - win_copy - Fix issue where the dest return value would be enclosed in single quote when dest is a folder - https://github.com/ansible/ansible/issues/45281
 - win_copy - Fix issues when using paths with glob like characters, e.g. ``[``, ``]``
 - win_domain - Do not fail if DC is already promoted but a reboot is required, return ``reboot_required: True``
+- win_domain - Fix checking for a domain introduced in a recent patch
 - win_domain - Fix when running without credential delegated authentication - https://github.com/ansible/ansible/issues/53182
 - win_file - Fix issue when managing hidden files and directories - https://github.com/ansible/ansible/issues/42466
 - win_file - Fix issues when using paths with glob like characters, e.g. ``[``, ``]``
@@ -759,10 +834,12 @@ Bugfixes
 - win_power_plan - Fix issue where win_power_plan failed on newer Windows 10 builds - https://github.com/ansible/ansible/issues/43827
 - win_psexec - Support executables with a space in the path
 - win_reboot - Fix reboot command validation failure when running under the psrp connection plugin
+- win_reboot - pass return value for ``test_command`` result when using the ``psrp`` connection plugin
 - win_reg_stat - Fix issue where the key's ``(Default)`` property was not being returned if it was set
 - win_reg_stat - Support registry paths with special characters - https://github.com/ansible/ansible/issues/41791
 - win_regedit - Fix issue where creating a new key would set the ``(Default)`` key property to an empty string instead of undefined
 - win_regedit - Support registry paths with special characters - https://github.com/ansible/ansible/issues/41791
+- win_region - Fix the check for ``format`` when running on the ``psrp`` connection plugin
 - win_route - Corrected issue where the wrong network interface was used for new static routes. - https://github.com/ansible/ansible/issues/28051
 - win_say - fix syntax error in module and get tests working
 - win_shortcut - Added idempotency checks when ``src`` is a special shell folder like ``shell:RecycleBinFolder``
@@ -779,6 +856,7 @@ Bugfixes
 - yum - fix "package == version" syntax (https://github.com/ansible/ansible/pull/47744)
 - yum - fix disable_excludes on systems with yum rhn plugin enabled (https://github.com/ansible/ansible/issues/53134)
 - yum - properly handle a proxy config in yum.conf for an unauthenticated proxy
+- yum allows comparison operators like '>=' for selecting package version
 - zabbix_hostmacro - Added missing validate_certs logic for running module against Zabbix servers with untrused SSL certificates (https://github.com/ansible/ansible/issues/47611)
 - zabbix_hostmacro - Fixed support for user macros with context (https://github.com/ansible/ansible/issues/46953)
 - zabbix_template - Failed template import will no longer leave empty templates configured on Zabbix server
@@ -825,6 +903,7 @@ Connection
 - napalm - Provides persistent connection using NAPALM
 - podman - Interact with an existing podman container
 - qubes - Interact with an existing QubesOS AppVM
+- vmware_tools - Execute tasks inside a VM via VMware Tools
 
 Httpapi
 ~~~~~~~
@@ -839,9 +918,11 @@ Httpapi
 Inventory
 ~~~~~~~~~
 
+- cloudscale - cloudscale.ch inventory source
 - docker_swarm - Ansible dynamic inventory plugin for Docker swarm nodes.
 - gitlab_runners - Ansible dynamic inventory plugin for Gitlab runners.
 - hcloud - Ansible dynamic inventory plugin for the Hetzner Cloud.
+- kubevirt - KubeVirt inventory source
 - linode - Ansible dynamic inventory plugin for Linode.
 - toml - Uses a specific TOML file as an inventory source.
 
@@ -904,14 +985,19 @@ azure
 - azure_rm_devtestlabartifactsource - Manage Azure DevTest Labs Artifacts Source instance.
 - azure_rm_devtestlabartifactsource_facts - Get Azure DevTest Lab Artifact Source facts.
 - azure_rm_devtestlabcustomimage - Manage Azure DevTest Lab Custom Image instance.
+- azure_rm_devtestlabcustomimage_facts - Get Azure DevTest Lab Custom Image facts.
 - azure_rm_devtestlabenvironment - Manage Azure DevTest Lab Environment instance.
+- azure_rm_devtestlabenvironment_facts - Get Azure Environment facts.
 - azure_rm_devtestlabpolicy - Manage Azure Policy instance.
+- azure_rm_devtestlabpolicy_facts - Get Azure DTL Policy facts.
 - azure_rm_devtestlabschedule - Manage Azure DevTest Lab Schedule instance.
+- azure_rm_devtestlabschedule_facts - Get Azure Schedule facts.
 - azure_rm_devtestlabvirtualmachine - Manage Azure DevTest Lab Virtual Machine instance.
 - azure_rm_devtestlabvirtualmachine_facts - Get Azure DevTest Lab Virtual Machine facts.
 - azure_rm_devtestlabvirtualnetwork - Manage Azure DevTest Lab Virtual Network instance.
 - azure_rm_devtestlabvirtualnetwork_facts - Get Azure DevTest Lab Virtual Network facts.
 - azure_rm_hdinsightcluster - Manage Azure HDInsight Cluster instance.
+- azure_rm_hdinsightcluster_facts - Get Azure HDInsight Cluster facts.
 - azure_rm_image_facts - Get facts about azure custom images.
 - azure_rm_loganalyticsworkspace - Manage Azure Log Analytics workspaces.
 - azure_rm_loganalyticsworkspace_facts - Get facts of Azure Log Analytics workspaces.
@@ -952,6 +1038,7 @@ azure
 - azure_rm_virtualmachinescalesetextension_facts - Get Azure Virtual Machine Scale Set Extension facts.
 - azure_rm_virtualmachinescalesetinstance - Get Azure Virtual Machine Scale Set Instance facts.
 - azure_rm_virtualmachinescalesetinstance_facts - Get Azure Virtual Machine Scale Set Instance facts.
+- azure_rm_virtualnetworkgateway - Manage Azure virtual network gateways.
 - azure_rm_virtualnetworkpeering - Manage Azure Virtual Network Peering.
 - azure_rm_virtualnetworkpeering_facts - Get facts of Azure Virtual Network Peering.
 - azure_rm_webappslot - Manage Azure Web App slot.
@@ -959,6 +1046,7 @@ azure
 cloudscale
 ^^^^^^^^^^
 
+- cloudscale_server_group - Manages server groups on the cloudscale.ch IaaS service
 - cloudscale_volume - Manages volumes on the cloudscale.ch IaaS service
 
 cloudstack
@@ -988,6 +1076,7 @@ docker
 - docker_prune - Allows to prune various docker objects
 - docker_stack - docker stack module
 - docker_swarm_info - Retrieves facts about Docker Swarm cluster.
+- docker_swarm_service_info - Retrieves information about docker services from a Swarm Manager
 - docker_volume_info - Retrieve facts about Docker volumes
 
 google
@@ -1079,6 +1168,11 @@ openstack
 
 - os_coe_cluster - Add/Remove COE cluster from OpenStack Cloud
 
+oracle
+^^^^^^
+
+- oci_vcn - Manage Virtual Cloud Networks(VCN) in OCI
+
 ovh
 ^^^
 
@@ -1090,8 +1184,15 @@ ovirt
 - ovirt_event - Create or delete an event in oVirt/RHV
 - ovirt_event_facts - This module can be used to retrieve facts about one or more oVirt/RHV events
 - ovirt_instance_type - Module to manage Instance Types in oVirt/RHV
+- ovirt_role - Module to manage roles in oVirt/RHV
 - ovirt_vnic_profile - Module to manage vNIC profile of network in oVirt/RHV
 
+podman
+^^^^^^
+
+- podman_image - Pull images for use by podman
+- podman_image_info - Gather info about images using podman
+
 scaleway
 ^^^^^^^^
 
@@ -1163,6 +1264,9 @@ Crypto
 - luks_device - Manage encrypted (LUKS) devices
 - openssh_cert - Generate OpenSSH host or user certificates.
 - openssh_keypair - Generate OpenSSH private and public keys.
+- openssl_certificate_info - Provide information of OpenSSL X.509 certificates
+- openssl_csr_info - Provide information of OpenSSL Certificate Signing Requests (CSR)
+- openssl_privatekey_info - Provide information for OpenSSL private keys
 
 acme
 ^^^^
@@ -1189,10 +1293,12 @@ postgresql
 - postgresql_idx - Create or drop indexes from a PostgreSQL database
 - postgresql_info - Gather information about PostgreSQL servers
 - postgresql_membership - Add or remove PostgreSQL roles from groups
+- postgresql_owner - Change an owner of PostgreSQL database object
 - postgresql_pg_hba - Add, remove or modifie a rule in a pg_hba file
 - postgresql_ping - Check remote PostgreSQL server availability
 - postgresql_query - Run PostgreSQL queries
 - postgresql_set - Change a PostgreSQL server configuration parameter
+- postgresql_slot - Add or remove slots from a PostgreSQL database
 - postgresql_table - Create, drop, or modify a PostgreSQL table
 - postgresql_tablespace - Add or remove PostgreSQL tablespaces from remote hosts
 
@@ -1201,6 +1307,14 @@ Files
 
 - read_csv - Read a CSV file
 
+Identity
+~~~~~~~~
+
+keycloak
+^^^^^^^^
+
+- keycloak_group - Allows administration of Keycloak groups via Keycloak API
+
 Messaging
 ~~~~~~~~~
 
@@ -1225,7 +1339,7 @@ Net Tools
 netbox
 ^^^^^^
 
-- netbox_device - Create or delete devices within Netbox
+- netbox_device - Create, update or delete devices within Netbox
 - netbox_interface - Creates or removes interfaces from Netbox
 - netbox_ip_address - Creates or removes IP addresses from Netbox
 - netbox_prefix - Creates or removes prefixes from Netbox
@@ -1702,10 +1816,12 @@ netvisor
 onyx
 ^^^^
 
+- onyx_buffer_pool - Configures Buffer Pool
 - onyx_igmp_interface - Configures IGMP interface parameters
 - onyx_igmp_vlan - Configures IGMP Vlan parameters
 - onyx_ptp_global - Configures PTP Global parameters
 - onyx_ptp_interface - Configures PTP on interface
+- onyx_vxlan - Configures Vxlan
 
 restconf
 ^^^^^^^^
@@ -1882,6 +1998,11 @@ purestorage
 - purefb_s3user - Create or delete FlashBlade Object Store account users
 - purefb_subnet - Manage network subnets in a Pure Storage FlashBlade
 
+vexata
+^^^^^^
+
+- vexata_volume - Manage volumes on Vexata VX100 storage arrays
+
 zfs
 ^^^
 
@@ -1897,6 +2018,7 @@ System
 - pids - Retrieves process IDs list if the process is running otherwise return empty list
 - selogin - Manages linux user to SELinux user mapping
 - xfconf - Edit XFCE4 Configurations
+- xfs_quota - Manage quotas on XFS filesystems
 
 Web Infrastructure
 ~~~~~~~~~~~~~~~~~~
@@ -1933,7 +2055,10 @@ Windows
 - win_credential - Manages Windows Credentials in the Credential Manager
 - win_dns_record - Manage Windows Server DNS records
 - win_domain_group_membership - Manage Windows domain group membership
+- win_format - Formats an existing volume or a new volume on an existing partition on Windows
 - win_hosts - Manages hosts file entries on Windows.
+- win_http_proxy - Manages proxy settings for WinHTTP
+- win_inet_proxy - Manages proxy settings for WinINet and Internet Explorer
 - win_optional_feature - Manage optional Windows features
 - win_partition - Creates, changes and removes partitions on Windows Server
 - win_psrepository - Adds, removes or updates a Windows PowerShell repository.

changelogs/fragments/40424_postgresql_db_not_failed_when_dump_err.yml

@@ -1,2 +1,2 @@
 bugfixes:
-  - postgresql_db - the module fails not always when pg_dump errors occured (https://github.com/ansible/ansible/issues/40424).
+  - postgresql_db - the module fails not always when pg_dump errors occurred (https://github.com/ansible/ansible/issues/40424).

changelogs/fragments/44811-xml-insertbefore-and-insertafter-parameters.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - xml - Introduce ``insertbefore`` and ``insertafter`` to specify the position (https://github.com/ansible/ansible/pull/44811)

changelogs/fragments/46483-role_names-change.yaml

@@ -1,7 +1,7 @@
 minor_changes:
   - magic variables - added a new ``ansible_role_names`` magic variable to include the names of roles being applied to
     the host both directly and indirectly (via dependencies).
-  - magic variabels - added a new ``ansible_play_role_names`` magic variable to mimic the old functionality of
+  - magic variables - added a new ``ansible_play_role_names`` magic variable to mimic the old functionality of
     ``role_names``. This variable only lists the names of roles being applied to the host directly, and does not
     include those added via dependencies
   - magic variables - added a new ``ansible_dependent_role_names`` magic variable to contain the names of roles

changelogs/fragments/47492-docker_network-add-ipv6-support.yaml

@@ -2,4 +2,4 @@
 minor_changes:
   - "docker_network - Add support for IPv6 networks."
 deprecated_features:
-  - "docker_network - Deprecate ``ipam_options`` in favour of ``ipam_config``."
+  - "docker_network - Deprecate ``ipam_options`` in favor of ``ipam_config``."

changelogs/fragments/47704-apt-warn-auto-intall.yml

@@ -1,3 +1,3 @@
 ---
 bugfixes:
-- apt - Show a warning hint in case apt auto-installs its dependecies.
+- apt - Show a warning hint in case apt auto-installs its dependencies.

changelogs/fragments/49904-rds_instance-datatype.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - Add variable type for performance_insights_retention_period (https://github.com/ansible/ansible/issues/49904).

changelogs/fragments/51825-vmware_deploy_ovf-add_folder_doc.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- Added documentation about the folder parameter with examples in vmware_deploy_ovf (https://github.com/ansible/ansible/issues/51825).

changelogs/fragments/53213-docker_swarm_service-option_groups.yaml

@@ -6,9 +6,9 @@ minor_changes:
   - "docker_swarm_service - Add option ``restart_config`` as a grouper for restart options."
   - "docker_swarm_service - Add option ``update_config`` as a grouper for update options."
 deprecated_features:
-  - "docker_swarm_service - Deprecate ``constraints`` in favour of ``placement``."
-  - "docker_swarm_service - Deprecate ``log_driver`` and ``log_driver_options`` in favour of ``logging``."
-  - "docker_swarm_service - Deprecate ``limit_cpu`` and ``limit_memory`` in favour of ``limits``."
-  - "docker_swarm_service - Deprecate ``reserve_cpu`` and ``reserve_memory`` in favour of ``reservations``."
-  - "docker_swarm_service - Deprecate ``restart_policy``, ``restart_policy_attempts``, ``restart_policy_delay`` and ``restart_policy_window`` in favour of ``restart_config``."
-  - "docker_swarm_service - Deprecate ``update_delay``, ``update_parallelism``, ``update_failure_action``, ``update_monitor``, ``update_max_failure_ratio`` and ``update_order`` in favour of ``update_config``."
+  - "docker_swarm_service - Deprecate ``constraints`` in favor of ``placement``."
+  - "docker_swarm_service - Deprecate ``log_driver`` and ``log_driver_options`` in favor of ``logging``."
+  - "docker_swarm_service - Deprecate ``limit_cpu`` and ``limit_memory`` in favor of ``limits``."
+  - "docker_swarm_service - Deprecate ``reserve_cpu`` and ``reserve_memory`` in favor of ``reservations``."
+  - "docker_swarm_service - Deprecate ``restart_policy``, ``restart_policy_attempts``, ``restart_policy_delay`` and ``restart_policy_window`` in favor of ``restart_config``."
+  - "docker_swarm_service - Deprecate ``update_delay``, ``update_parallelism``, ``update_failure_action``, ``update_monitor``, ``update_max_failure_ratio`` and ``update_order`` in favor of ``update_config``."

changelogs/fragments/54955-docker_container-log_options-strings.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "docker_container - fix idempotency of ``log_options`` when non-string values are used. Also warn user that this is the case."

changelogs/fragments/55078-redfish_utils_fix_406_not_acceptable_issue_with_some_oob_controllers.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- redfish_utils - fix "406 Not Acceptable" issue with some OOB controllers (https://github.com/ansible/ansible/issues/55078)

changelogs/fragments/55142-openssl_csr-crypto-backend-san.yml

@@ -0,0 +1,3 @@
+bugfixes:
+- "openssl_csr - the cryptography backend's idempotency checking for basic constraints was broken."
+- "openssl_csr - SAN normalization for IP addresses for the pyOpenSSL backend was broken."

changelogs/fragments/55203-fix-for-removing-subscription-id-from-facts.yaml

@@ -0,0 +1,3 @@
+---
+bugfixes:
+- "Fixes an issue when subscription_id is masked in the output when it's passed as one of the parameters."

changelogs/fragments/55258-docker_host_info-old-docker-py.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "docker_host_info - ``network_filters`` needs docker-py 2.0.2, ``disk_usage`` needs docker-py 2.2.0."

changelogs/fragments/55258-docker_swarm_service_info-old-docker-py.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "docker_swarm_service_info - work around problems with older docker-py versions such as 2.0.2."

changelogs/fragments/55266-purefa_facts_remove_line.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+ - "purefa_facts - remove unnecessary line that could cause failure in rare circumstances."

changelogs/fragments/55278-cryto-use-bundled-ipaddress.yml

@@ -0,0 +1,3 @@
+bugfixes:
+- "openssl_csr, openssl_csr_info - use ``ipaddress`` module bundled with Ansible for normalizations needed for pyOpenSSL backend."
+- "acme_certificate - use ``ipaddress`` module bundled with Ansible for normalizations needed for OpenSSL backend."

changelogs/fragments/55384-netconf-import.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Move netconf import errors from import to use.

changelogs/fragments/55515-use-active-state-for-any_errors_fatal.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Be sure to use the active state when checking for any_errors_fatal

changelogs/fragments/55546-fixed-replacing-lb-with-ag-in-vmss.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- Fixes replacing load balancer with application gateway in Azure virtualmachine scaleset, as leaning up old load balancer was not done properly.

changelogs/fragments/55591-docker_swarm_service-fix-uid-gid-secrets-config-type.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- "docker_swarm_service - Change the type of options ``gid`` and ``uid`` on ``secrets`` and ``configs`` to ``str``."

changelogs/fragments/55619-vultr_server_idempotency.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - vultr_server - Fix idempotency for options ``ipv6_enabled`` and ``private_network_enabled``.

changelogs/fragments/55681-azure_rm_manageddisk.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+    - Enable azure manged disk test

changelogs/fragments/55688-azure_rm_resourcegroup.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - add resource group test

changelogs/fragments/55693-fixing-final-function-app-properties.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - azure_rm_functionapp - adding two properties which need to be set by default, otherwise function app won't behave correctly in Azure Portal.

changelogs/fragments/56145-ios-net_get-net_put-update.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- Fix net_get and net_put task run failure - https://github.com/ansible/ansible/pull/56145

changelogs/fragments/allow_inv_plugin_loading.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - allow loading inventory plugins adjacent to playbooks

changelogs/fragments/bad_empty_play.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - re allow empty plays for now, but add deprecation msg.

changelogs/fragments/docker_network-requirements.yaml

@@ -2,4 +2,4 @@
 minor_changes:
   - "docker_network - Minimum docker-py version increased from ``1.8.0`` to ``1.10.0``."
   - "docker_network - Minimum docker server version increased from ``1.9.0`` to ``1.10.0``."
-  - "docker_network - Minimum docker API version explcitly set to ``1.22``."
+  - "docker_network - Minimum docker API version explicitly set to ``1.22``."

changelogs/fragments/ensure_discovery_unsafe.yml

@@ -0,0 +1,3 @@
+bugfixes:
+    - SECURITY Fixed the python interpreter detection, added in 2.8.0alpha1, to properly mark the returned data as untemplatable.
+      This prevents a malicious managed machine from running code on the controller via templating.

changelogs/fragments/ensure_facts_safe.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - ensure module results and facts are marked untrusted as templates for safer use within the same task

changelogs/fragments/fix_pull_extra.yml

@@ -1,2 +1,2 @@
 bugfixes:
-    - fix ansible-pull hanlding of extra args, complex quoting is needed for inline JSON
+    - fix ansible-pull handling of extra args, complex quoting is needed for inline JSON

changelogs/fragments/gitlab-deprecated-version.yaml

@@ -0,0 +1,3 @@
+bugfixes:
+- gitlab modules - Update version deprecations to use strings instead of integers
+  so that ``2.10`` isn't converted to ``2.1``. (https://github.com/ansible/ansible/pull/55395)

changelogs/fragments/inv_fixes.yml

@@ -1,2 +1,2 @@
 bugfixes:
-    - Give user better error messages and more information on verbose about inventory plugin behaviour
+    - Give user better error messages and more information on verbose about inventory plugin behavior

changelogs/fragments/k8s-fix_wait_for_response.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - Fix API call to _wait_for_response in k8s modules (https://github.com/ansible/ansible/pull/53937).

changelogs/fragments/loop-cache-include-apply.yml

@@ -1,2 +1,2 @@
 bugfixes:
-- delegate_to - Fix issue where delegate_to was upplied via ``apply`` on an include, where a loop was present on the include
+- delegate_to - Fix issue where delegate_to was applied via ``apply`` on an include, where a loop was present on the include

changelogs/fragments/meraki_content_filtering-redundant-calls.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "meraki_static_route - Module would make unnecessary API calls to Meraki when ``net_id`` is specified in task."

changelogs/fragments/meraki_static_route_api_calls.yml

@@ -0,0 +1,3 @@
+---
+bugfixes:
+- "meraki_static_route - Module would make unnecessary API calls to Meraki when ``net_id`` is specified in task."

changelogs/fragments/meraki_vlan_api_calls.yml

@@ -0,0 +1,3 @@
+---
+bugfixes:
+- "meraki_vlan - Module would make unnecessary API calls to Meraki when net_id is specified in task."

changelogs/fragments/networkos_config_src_option_fix.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Fix invalid src option return response for network config modules (https://github.com/ansible/ansible/pull/56076)

changelogs/fragments/no_empty_groups.yml

@@ -1,2 +1,2 @@
 bugfixes:
-    - avoid empty groups in ansbile-inventory JSON output as they will be interpreted as hosts
+    - avoid empty groups in ansible-inventory JSON output as they will be interpreted as hosts

changelogs/fragments/persistent_loading.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - pass correct loading context to persistent connections

changelogs/fragments/postgresql_idx-remove-useless-lines.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - postgresql_idx - removed useless rows that remained after the previous refactoring

changelogs/fragments/postgresql_slot-fix-sslrootcert.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - postgresql_slot - fixed sslrootcert mapping to psycopg2 connection string

changelogs/fragments/ps-basic-json.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- Ansible.Basic - Fix issue when deserializing a JSON string that is not a dictionary - https://github.com/ansible/ansible/pull/55691

changelogs/fragments/psrp-fetch.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- psrp - Fix issues when fetching large files causing a memory leak - https://github.com/ansible/ansible/issues/55239

changelogs/fragments/psrp-output.yaml

@@ -0,0 +1,3 @@
+bugfixes:
+- psrp - Fix blank newlines appearing before ``stdout`` when using ``script`` or ``raw`` with the ``psrp`` connection plugin
+- psrp - Fix issues with propagating errors back to Ansible with ``raw`` tasks

changelogs/fragments/systemd-warn-on-chroot.yaml

@@ -1,2 +1,2 @@
 bugfixes:
-  - systemd - warn when exeuting in a chroot environment rather than failing (https://github.com/ansible/ansible/pull/43904)
+  - systemd - warn when executing in a chroot environment rather than failing (https://github.com/ansible/ansible/pull/43904)

changelogs/fragments/tower_job_wait-wrong_examples.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - tower_job_wait - Fixed wrong variable specification in examples

changelogs/fragments/user-aix-shadow-file-parsing.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - user - properly parse the shadow file on AIX (https://github.com/ansible/ansible/issues/54461)

changelogs/fragments/v2.8.0_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2019-05-16
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.8.0b1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2019-04-15
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.8.0rc1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2019-04-25
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.8.0rc2_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2019-05-01
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.8.0rc3_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2019-05-10
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/vmware_check_ssl_cert.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- vmware - The VMware modules now enable the SSL certificate check unless ``validate_certs`` is ``false``.

changelogs/fragments/vmware_portgroup_list_host.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- vmware_portgroup accepts list of ESXi hostsystem. Modified get_all_host_objs API to accept list of hostsystems.

changelogs/fragments/vmware_tools_fix_urllib3_import.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+- Try to use bundled urllib3 first, then falls back to non-bundled version in vmware_tools (https://github.com/ansible/ansible/pull/55187).

changelogs/fragments/vsphere_guest-corrected-state-operations.yml

@@ -0,0 +1,4 @@
+---
+bugfixes:
+  - vsphere_guest - creating machines without vm_extra_config allowed
+  - vsphere_guest - powering on/off absent virtual machine will fail

changelogs/fragments/warn_bad_local_fact.yml

@@ -1,2 +1,2 @@
 bugfixes:
-    - issue a warning when local fact is not correctly loaded, old behaviour just updated fact value with the error.
+    - issue a warning when local fact is not correctly loaded, old behavior just updated fact value with the error.

changelogs/fragments/win_become-passwordless.yaml

@@ -1,3 +1,3 @@
 minor_changes:
 - windows become - Add support for passwordless become.
-- windows become - Moved to shared C# util so modules can utilise the code.
+- windows become - Moved to shared C# util so modules can utilize the code.

changelogs/fragments/win_domain-setup.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- win_domain - Fix checking for a domain introduced in a recent patch

changelogs/fragments/win_reboot-psrp-command.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- win_reboot - pass return value for ``test_command`` result when using the ``psrp`` connection plugin

changelogs/fragments/win_region-format.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- win_region - Fix the check for ``format`` when running on the ``psrp`` connection plugin

changelogs/fragments/winrm-ansible-conn-error.yaml

@@ -1,3 +1,3 @@
 ---
 minor_changes:
-  - Raise AnsibleConnectionError on winrm connnection errors
+  - Raise AnsibleConnectionError on winrm connection errors

docs/bin/plugin_formatter.py

@@ -275,8 +275,11 @@ def get_plugin_info(module_dir, limit_to=None, verbose=False):
                 module = module.replace("_", "", 1)
                 aliases = module_info[source].get('aliases', set())
                 aliases.add(module)
+                aliases_deprecated = module_info[source].get('aliases_deprecated', set())
+                aliases_deprecated.add(module)
                 # In case we just created this via get()'s fallback
                 module_info[source]['aliases'] = aliases
+                module_info[source]['aliases_deprecated'] = aliases_deprecated
                 continue
             else:
                 # Handle deprecations
@@ -340,6 +343,7 @@ def get_plugin_info(module_dir, limit_to=None, verbose=False):
                                'source': os.path.relpath(module_path, module_dir),
                                'deprecated': deprecated,
                                'aliases': module_info[module].get('aliases', set()),
+                               'aliases_deprecated': module_info[module].get('aliases_deprecated', set()),
                                'metadata': metadata,
                                'doc': doc,
                                'examples': examples,
@@ -404,6 +408,7 @@ def jinja2_environment(template_dir, typ, plugin_type):
         env.filters['documented_type'] = documented_type
         env.tests['list'] = test_list
         templates['plugin'] = env.get_template('plugin.rst.j2')
+        templates['plugin_deprecation_stub'] = env.get_template('plugin_deprecation_stub.rst.j2')
 
         if plugin_type == 'module':
             name = 'modules'
@@ -570,6 +575,26 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi
 
         write_data(text, output_dir, outputname, module)
 
+        # Create deprecation stub pages for deprecated aliases
+        if module_map[module]['aliases']:
+            for alias in module_map[module]['aliases']:
+                if alias in module_map[module]['aliases_deprecated']:
+                    doc['alias'] = alias
+
+                    display.v('about to template %s (deprecation alias %s)' % (module, alias))
+                    display.vvvvv(pp.pformat(doc))
+                    try:
+                        text = templates['plugin_deprecation_stub'].render(doc)
+                    except Exception as e:
+                        display.warning(msg="Could not parse %s (deprecation alias %s) due to %s" % (module, alias, e))
+                        continue
+
+                    if LooseVersion(jinja2.__version__) < LooseVersion('2.10'):
+                        # jinja2 < 2.10's indent filter indents blank lines.  Cleanup
+                        text = re.sub(' +\n', '\n', text)
+
+                    write_data(text, output_dir, outputname, alias)
+
 
 def process_categories(plugin_info, categories, templates, output_dir, output_name, plugin_type):
     # For some reason, this line is changing plugin_info:

docs/docsite/README.md

@@ -1,4 +1,4 @@
-Homepage and documentation source for Ansible
+Homepage and Documentation Source for Ansible
 =============================================
 
 This project hosts the source behind [docs.ansible.com](https://docs.ansible.com/)
@@ -15,7 +15,7 @@ If you do not want to learn the reStructuredText format, you can also [file issu
 
 Note that module documentation can actually be [generated from a DOCUMENTATION docstring][module-docs] in the modules directory, so corrections to modules written as such need to be made in the module source, rather than in docsite source.
 
-To install sphinx and the required theme, install pip and then "pip install sphinx sphinx_rtd_theme"
+To install sphinx and the required theme, install ``pip`` and then ``pip install sphinx sphinx_rtd_theme``
 
 [file issues]: https://github.com/ansible/ansible/issues
 [module-docs]: https://docs.ansible.com/developing_modules.html#documenting-your-module
@@ -23,7 +23,7 @@ To install sphinx and the required theme, install pip and then "pip install sphi
 HEADERS
 =======
 
-RST allows for arbitrary hierchy for the headers, it will 'learn on the fly' but we want a standard so all our documents can follow:
+RST allows for arbitrary hierarchy for the headers, it will 'learn on the fly'. We also want a standard that all our documents can follow:
 
 ```
 ##########################

docs/docsite/_themes/sphinx_rtd_theme/layout.html

@@ -156,7 +156,7 @@
                 <div class="DocSiteProduct-logoText">
                     Ansible  
                     <div class="DocSiteProduct-CurrentVersion" align="right">
-                      devel
+                      2.8
                   </div>
                 </div>
             </div>

docs/docsite/_themes/sphinx_rtd_theme/static/css/theme.css

@@ -1758,7 +1758,7 @@ footer span.commit code,footer span.commit .rst-content tt,.rst-content footer s
 .rst-content .sidebar p,.rst-content .sidebar ul,.rst-content .sidebar dl{font-size:90%}
 .rst-content .sidebar .last{margin-bottom:0}
 .rst-content .sidebar .sidebar-title{display:block;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;font-weight:bold;background:#e1e4e5;padding:6px 12px;margin:-24px;margin-bottom:24px;font-size:100%}
-.rst-content .highlighted{background:#F1C40F;display:inline-block;font-weight:bold;padding:0 6px}
+.rst-content .highlighted{background:#F1C40F;display:inline-block;font-weight:bold;}
 .rst-content .footnote-reference,.rst-content .citation-reference{vertical-align:baseline;position:relative;top:-0.4em;line-height:0;font-size:90%}
 .rst-content table.docutils.citation,.rst-content table.docutils.footnote{background:none;border:none;color:gray}
 .rst-content table.docutils.citation td,.rst-content table.docutils.citation tr,.rst-content table.docutils.footnote td,.rst-content table.docutils.footnote tr{border:none;background-color:transparent !important;white-space:normal}

docs/docsite/_themes/sphinx_rtd_theme/theme.conf

@@ -10,7 +10,7 @@ collapse_navigation = False
 sticky_navigation = True
 navigation_depth = 4
 includehidden = True
-titles_only = 
+titles_only =
 logo_only =
 display_version = True
 prev_next_buttons_location = bottom

docs/docsite/rst/conf.py

@@ -34,7 +34,7 @@ sys.path.append(os.path.abspath(os.path.join('..', '_extensions')))
 # the repository version needs to be the one that is loaded:
 sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib')))
 
-VERSION = '2.7'
+VERSION = '2.8'
 AUTHOR = 'Ansible, Inc'
 
 
@@ -135,6 +135,7 @@ html_short_title = 'Ansible Documentation'
 
 html_theme_options = {
     'canonical_url': "https://docs.ansible.com/ansible/latest/",
+    'collapse_navigation': "True"
 }
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name

docs/docsite/rst/dev_guide/developing_locally.rst

@@ -5,7 +5,7 @@
 Adding modules and plugins locally
 **********************************
 
-.. contents:: Topics
+.. contents::
    :local:
 
 The easiest, quickest, and most popular way to extend Ansible is to copy or write a module or a plugin for local use. You can store local modules and plugins on your Ansible control node for use within your team or organization. You can also share a local plugin or module by embedding it in a role and publishing it on Ansible Galaxy. If you've been using roles off Galaxy, you may have been using local modules and plugins without even realizing it. If you're using a local module or plugin that already exists, this page is all you need.
@@ -26,8 +26,8 @@ Modules and plugins: what's the difference?
 ===========================================
 If you're looking to add local functionality to Ansible, you may be wondering whether you need a module or a plugin. Here's a quick overview of the differences:
 
-* Modules are reusable, standalone scripts that can be used by the Ansible API, the :command:`ansible` command, or the :command:`ansible-playbook` command. Modules provide a defined interface, accepting arguments and returning information to Ansible by printing a JSON string to stdout before exiting.
-* Plugins are shared code that can be used by any module. They provide abilities like caching information or copying files that are useful for many modules.
+* Modules are reusable, standalone scripts that can be used by the Ansible API, the :command:`ansible` command, or the :command:`ansible-playbook` command. Modules provide a defined interface, accepting arguments and returning information to Ansible by printing a JSON string to stdout before exiting. Modules execute on the target system (usually that means on a remote system) in separate processes.
+* :ref:`Plugins <plugins_lookup>` augment Ansible's core functionality and execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more.
 
 .. _local_modules:
 

docs/docsite/rst/dev_guide/developing_module_utilities.rst

@@ -1,87 +1,77 @@
-.. _appendix_module_utilities:
+.. _developing_module_utilities:
 
-**************************
-Appendix: Module Utilities
-**************************
+*************************************
+Using and Developing Module Utilities
+*************************************
 
-Ansible provides a number of module utilities that provide helper functions that you can use when developing your own modules. The ``basic.py`` module utility provides the main entry point for accessing the Ansible library, and all Python Ansible modules must, at minimum, import ``AnsibleModule``::
+Ansible provides a number of module utilities, or snippets of shared code, that
+provide helper functions you can use when developing your own modules. The
+``basic.py`` module utility provides the main entry point for accessing the
+Ansible library, and all Python Ansible modules must import something from
+``ansible.module_utils``. A common option is to import ``AnsibleModule``::
 
   from ansible.module_utils.basic import AnsibleModule
 
-If you need to share Python code between some of your own local modules, you can use Ansible's ``module_utils`` directories for this. When you run ``ansible-playbook``, Ansible will merge any files in the local ``module_utils`` directory into the ``ansible.module_utils`` namespace. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file in the root location where your playbook lives, and then import it in your modules like so::
+The ``ansible.module_utils`` namespace is not a plain Python package: it is
+constructed dynamically for each task invocation, by extracting imports and
+resolving those matching the namespace against a :ref:`search path <ansible_search_path>` derived from the
+active configuration.
+
+To reduce the maintenance burden on your own local modules, you can extract
+duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file like this::
 
   from ansible.module_utils.my_shared_code import MySharedCodeClient
 
-Your custom ``module_utils`` directories can live in the root directory of your playbook, or in the individual role directories, or in the directories specified by the ``ANSIBLE_MODULE_UTILS`` configuration setting.
+When you run ``ansible-playbook``, Ansible will merge any files in your local ``module_utils`` directories into the ``ansible.module_utils`` namespace in the order defined by the :ref:`Ansible search path <ansible_search_path>`.
 
-Ansible ships with the following list of ``module_utils`` files. The module utility source code lives in the ``./lib/ansible/module_utils`` directory under your main Ansible path - for more details on any specific module utility, please see the source code.
+Naming and finding module utilities
+===================================
+
+You can generally tell what a module utility does from its name and/or its location. For example, ``openstack.py`` contains utilities for modules that work with OpenStack instances.
+Generic utilities (shared code used by many different kinds of modules) live in the ``common`` subdirectory or in the root directory. Utilities
+used by a particular set of modules generally live in a sub-directory that mirrors
+the directory for those modules. For example:
+
+* ``lib/ansible/module_utils/urls.py`` contains shared code for parsing URLs
+* ``lib/ansible/module_utils/storage/emc/`` contains shared code related to EMC
+*  ``lib/ansible/modules/storage/emc/`` contains modules related to EMC
+
+Following this pattern with your own module utilities makes everything easy to find and use.
+
+.. _standard_mod_utils:
+
+Standard module utilities
+=========================
+
+Ansible ships with an extensive library of ``module_utils`` files.
+You can find the module
+utility source code in the ``lib/ansible/module_utils`` directory under
+your main Ansible path. We've described the most widely used utilities below. For more details on any specific module utility,
+please see the `source code for module_utils <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils>`_.
 
 .. include:: shared_snippets/licensing.txt
 
-- alicloud_ecs.py - Definitions and utilities for modules working with Alibaba Cloud ECS.
-- api.py - Adds shared support for generic API modules.
-- azure_rm_common.py - Definitions and utilities for Microsoft Azure Resource Manager template deployments.
-- basic.py - General definitions and helper utilities for Ansible modules.
-- cloudstack.py  - Utilities for CloudStack modules.
-- database.py - Miscellaneous helper functions for PostGRES and MySQL
-- docker_common.py - Definitions and helper utilities for modules working with Docker.
-- ec2.py - Definitions and utilities for modules working with Amazon EC2
-- facts/- Folder containing helper functions for modules that return facts. See https://github.com/ansible/ansible/pull/23012 for more information.
-- gce.py - Definitions and helper functions for modules that work with Google Compute Engine resources.
-- ismount.py - Contains single helper function that fixes os.path.ismount
-- keycloak.py - Definitions and helper functions for modules working with the Keycloak API
-- known_hosts.py - utilities for working with known_hosts file
-- manageiq.py - Functions and utilities for modules that work with ManageIQ platform and its resources.
-- memset.py - Helper functions and utilities for interacting with Memset's API.
-- mysql.py - Allows modules to connect to a MySQL instance
-- netapp.py - Functions and utilities for modules that work with the NetApp storage platforms.
-- network/a10/a10.py - Utilities used by the a10_server module to manage A10 Networks devices.
-- network/aci/aci.py - Definitions and helper functions for modules that manage Cisco ACI Fabrics.
-- network/aireos/aireos.py - Definitions and helper functions for modules that manage Cisco WLC devices.
-- network/aos/aos.py - Module support utilities for managing Apstra AOS Server.
-- network/aruba/aruba.py - Helper functions for modules working with Aruba networking devices.
-- network/asa/asa.py - Module support utilities for managing Cisco ASA network devices.
-- network/avi/avi.py - Helper functions for modules working with AVI networking devices.
-- network/bigswitch/bigswitch_utils.py - Utilities used by the bigswitch module to manage Big Switch Networks devices.
-- network/cloudengine/ce.py - Module support utilities for managing Huawei Cloudengine switch.
-- network/cnos/cnos.py - Helper functions for modules working on devices running Lenovo CNOS.
-- network/common/config.py - Configuration utility functions for use by networking modules
-- network/common/netconf.py - Definitions and helper functions for modules that use Netconf transport.
-- network/common/parsing.py - Definitions and helper functions for Network modules.
-- network/common/network.py - Functions for running commands on networking devices
-- network/common/utils.py - Defines commands and comparison operators and other utilises for use in networking modules
-- network/dellos6/dellos6.py - Module support utilities for managing device running Dell OS6.
-- network/dellos9/dellos9.py - Module support utilities for managing device running Dell OS9.
-- network/dellos10/dellos10.py - Module support utilities for managing device running Dell OS10.
-- network/enos/enos.py - Helper functions for modules working with Lenovo ENOS devices.
-- network/eos/eos.py - Helper functions for modules working with EOS networking devices.
-- network/fortios/fortios.py - Module support utilities for managing FortiOS devices.
-- network/ios/ios.py - Definitions and helper functions for modules that manage Cisco IOS networking devices
-- network/iosxr/iosxr.py - Definitions and helper functions for modules that manage Cisco IOS-XR networking devices.
-- network/ironware/ironware.py - Module support utilities for managing Brocade IronWare devices.
-- network/junos/junos.py -  Definitions and helper functions for modules that manage Junos networking devices.
-- network/meraki/meraki.py - Utilities specifically for the Meraki network modules.
-- network/netscaler/netscaler.py - Utilities specifically for the netscaler network modules.
-- network/nso/nso.py - Utilities for modules that work with Cisco NSO.
-- network/nxos/nxos.py - Contains definitions and helper functions specific to Cisco NXOS networking devices.
-- network/onyx/onyx.py - Definitions and helper functions for modules that manage Mellanox ONYX networking devices.
-- network/ordance/ordance.py - Module support utilities for managing Ordnance devices.
-- network/sros/sros.py - Helper functions for modules working with Open vSwitch bridges.
-- network/vyos/vyos.py - Definitions and functions for working with VyOS networking
-- openstack.py - Utilities for modules that work with Openstack instances.
-- openswitch.py - Definitions and helper functions for modules that manage OpenSwitch devices
-- powershell.ps1 - Utilities for working with Microsoft Windows clients
-- pure.py - Functions and utilities for modules that work with the Pure Storage storage platforms.
-- pycompat24.py - Exception workaround for Python 2.4.
-- rax.py -  Definitions and helper functions for modules that work with Rackspace resources.
-- redhat.py - Functions for modules that manage Red Hat Network registration and subscriptions
-- service.py - Contains utilities to enable modules to work with Linux services (placeholder, not in use).
-- shell.py - Functions to allow modules to create shells and work with shell commands
-- six/__init__.py - Bundled copy of the `Six Python library <https://pythonhosted.org/six/>`_ to aid in writing code compatible with both Python 2 and Python 3.
-- splitter.py - String splitting and manipulation utilities for working with Jinja2 templates
-- urls.py - Utilities for working with http and https requests
-- utm_utils.py - Contains base class for creating new Sophos UTM Modules and helper functions for handling the rest interface of Sophos UTM
-- vca.py - Contains utilities for modules that work with VMware vCloud Air
-- vexata.py - Utilities for modules that work with Vexata storage platforms.
-- vmware.py - Contains utilities for modules that work with VMware vSphere VMs
-- xenserver.py - Contains utilities for modules that work with XenServer.
+- ``api.py`` - Supports generic API modules
+- ``basic.py`` - General definitions and helper utilities for Ansible modules
+- ``common/dict_transformations.py`` - Helper functions for dictionary transformations
+- ``common/file.py`` - Helper functions for working with files
+- ``common/text/`` - Helper functions for converting and formatting text.
+- ``common/parameters.py`` - Helper functions for dealing with module parameters
+- ``common/sys_info.py`` - Functions for getting distribution and platform information
+- ``common/validation.py`` - Helper functions for validating module parameters against a module argument spec
+- ``facts/`` - Directory of utilities for modules that return facts. See `PR 23012 <https://github.com/ansible/ansible/pull/23012>`_ for more information
+- ``ismount.py`` - Single helper function that fixes os.path.ismount
+- ``json_utils.py`` - Utilities for filtering unrelated output around module JSON output, like leading and trailing lines
+- ``known_hosts.py`` - utilities for working with known_hosts file
+- ``network/common/config.py`` - Configuration utility functions for use by networking modules
+- ``network/common/netconf.py`` - Definitions and helper functions for modules that use Netconf transport
+- ``network/common/parsing.py`` - Definitions and helper functions for Network modules
+- ``network/common/network.py`` - Functions for running commands on networking devices
+- ``network/common/utils.py`` - Defines commands and comparison operators and other utilises for use in networking modules
+- ``powershell/`` - Directory of definitions and helper functions for Windows PowerShell modules
+- ``pycompat24.py`` - Exception workaround for Python 2.4
+- ``service.py`` - Utilities to enable modules to work with Linux services (placeholder, not in use)
+- ``shell.py`` - Functions to allow modules to create shells and work with shell commands
+- ``six/__init__.py`` - Bundled copy of the `Six Python library <https://pythonhosted.org/six/>`_ to aid in writing code compatible with both Python 2 and Python 3
+- ``splitter.py`` - String splitting and manipulation utilities for working with Jinja2 templates
+- ``urls.py`` - Utilities for working with http and https requests

docs/docsite/rst/dev_guide/developing_modules_best_practices.rst

@@ -67,7 +67,7 @@ Python tips
 Importing and using shared code
 ===============================
 
-* Use shared code whenever possible - don't reinvent the wheel. Ansible offers the ``AnsibleModule`` common Python code, plus :ref:`utilities <appendix_module_utilities>` for many common use cases and patterns.
+* Use shared code whenever possible - don't reinvent the wheel. Ansible offers the ``AnsibleModule`` common Python code, plus :ref:`utilities <developing_module_utilities>` for many common use cases and patterns. You can also create documentation fragments for docs that apply to multiple modules.
 * Import ``ansible.module_utils`` code in the same place as you import other libraries.
 * Do NOT use wildcards (*) for importing other python modules; instead, list the function(s) you are importing (for example, ``from some.other_python_module.basic import otherFunction``).
 * Import custom packages in ``try``/``except``, capture any import errors, and handle them with ``fail_json()`` in ``main()``. For example:

docs/docsite/rst/dev_guide/developing_modules_checklist.rst

@@ -5,7 +5,9 @@
 Contributing your module to Ansible
 ***********************************
 
-If you want to contribute a module to Ansible, you must meet our objective and subjective requirements. Modules accepted into the `main project repo <https://github.com/ansible/ansible>`_ ship with every Ansible installation. However, contributing to the main project isn't the only way to distribute a module - you can embed modules in roles on Galaxy or simply share copies of your module code for :ref:`local use <developing_locally>`.
+If you want to contribute a module to Ansible, you must meet our objective and subjective requirements. Please read the details below, and also review our :ref:`tips for module development <developing_modules_best_practices>`.
+
+Modules accepted into the `main project repo <https://github.com/ansible/ansible>`_ ship with every Ansible installation. However, contributing to the main project isn't the only way to distribute a module - you can embed modules in roles on Galaxy or simply share copies of your module code for :ref:`local use <developing_locally>`.
 
 Contributing to Ansible: objective requirements
 ===============================================
@@ -37,5 +39,6 @@ If your module meets our objective requirements, we'll review your code to see i
 Other checklists
 ================
 
+* :ref:`Tips for module development <developing_modules_best_practices>`.
 * `Amazon development checklist <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/amazon/GUIDELINES.md>`_.
 * :ref:`Windows development checklist <developing_modules_general_windows>`.

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -23,21 +23,23 @@ Every Ansible module written in Python must begin with seven standard sections i
 
 .. _shebang:
 
-Python shebang
-==============
+Python shebang & UTF-8 coding
+===============================
 
 Every Ansible module must begin with ``#!/usr/bin/python`` - this "shebang" allows ``ansible_python_interpreter`` to work.
+This is immediately followed by ``# -*- coding: utf-8 -*-`` to clarify that the file is UTF-8 encoded.
 
 .. _copyright:
 
 Copyright and license
 =====================
 
-After the shebang, there should be a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
+After the shebang and UTF-8 coding, there should be a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
 
 .. code-block:: python
 
     #!/usr/bin/python
+    # -*- coding: utf-8 -*-
 
     # Copyright: (c) 2018, Terry Jones <terry.jones@example.org>
     # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
@@ -47,6 +49,7 @@ Major additions to the module (for instance, rewrites) may add additional copyri
 .. code-block:: python
 
     #!/usr/bin/python
+    # -*- coding: utf-8 -*-
 
     # Copyright: (c) 2017, [New Contributor(s)]
     # Copyright: (c) 2015, [Original Contributor(s)]
@@ -57,7 +60,7 @@ Major additions to the module (for instance, rewrites) may add additional copyri
 ANSIBLE_METADATA block
 ======================
 
-After the shebang, the copyright, and the license, your module file should contain an ``ANSIBLE_METADATA`` section. This section provides information about the module for use by other tools. For new modules, the following block can be simply added into your module:
+After the shebang, the UTF-8 coding, the copyright, and the license, your module file should contain an ``ANSIBLE_METADATA`` section. This section provides information about the module for use by other tools. For new modules, the following block can be simply added into your module:
 
 .. code-block:: python
 
@@ -96,10 +99,10 @@ Ansible metadata fields
    The default value is a single element list ["preview"]. The following strings are valid
    statuses and have the following meanings:
 
-   :stableinterface: The module's parameters are stable. Every effort will be made not to remove parameters or change
+   :stableinterface: The module's options (the parameters or arguments it accepts) are stable. Every effort will be made not to remove options or change
       their meaning. **Not** a rating of the module's code quality.
    :preview: The module is in tech preview. It may be
-      unstable, the parameters may change, or it may require libraries or
+      unstable, the options may change, or it may require libraries or
       web services that are themselves subject to incompatible changes.
    :deprecated: The module is deprecated and will be removed in a future release.
    :removed: The module is not present in the release. A stub is
@@ -111,13 +114,13 @@ Ansible metadata fields
 DOCUMENTATION block
 ===================
 
-After the shebang, the copyright line, the license, and the ``ANSIBLE_METADATA`` section comes the ``DOCUMENTATION`` block. Ansible's online module documentation is generated from the ``DOCUMENTATION`` blocks in each module's source code. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file. You can start by copying our `example documentation string <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_ into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
+After the shebang, the UTF-8 coding, the copyright line, the license, and the ``ANSIBLE_METADATA`` section comes the ``DOCUMENTATION`` block. Ansible's online module documentation is generated from the ``DOCUMENTATION`` blocks in each module's source code. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file. You can start by copying our `example documentation string <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_ into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
 
 Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts.
     * Descriptions should always start with a capital letter and end with a full stop. Consistency always helps.
     * Verify that arguments in doc and module spec dict are identical.
     * For password / secret arguments no_log=True should be set.
-    * If an optional parameter is sometimes required, reflect this fact in the documentation, e.g. "Required when I(state=present)."
+    * If an option is only sometimes required, describe the conditions. For example, "Required when I(state=present)."
     * If your module allows ``check_mode``, reflect this fact in the documentation.
 
 Each documentation field is described below. Before committing your module documentation, please test it at the command line and as HTML:
@@ -147,16 +150,19 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
   * A detailed description (generally two or more sentences).
   * Must be written in full sentences, i.e. with capital letters and periods/full stops.
   * Shouldn't mention the module name.
+  * Make use of multiple entries rather than using one long paragraph.
+  * Don't quote complete values unless it is required by YAML.
 
 :version_added:
 
   * The version of Ansible when the module was added.
-  * This is a string, and not a float, i.e. ``version_added: "2.1"``
+  * This is a string, and not a float, i.e. ``version_added: '2.1'``
 
 :author:
 
   * Name of the module author in the form ``First Last (@GitHubID)``.
   * Use a multi-line list if there is more than one author.
+  * Don't use quotes as it should not be required by YAML.
 
 :deprecated:
 
@@ -164,19 +170,22 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 
 :options:
 
+  * Options are often called `parameters` or `arguments`. Because the documentation field is called `options`, we will use that term.
   * If the module has no options (for example, it's a ``_facts`` module), all you need is one line: ``options: {}``.
-  * If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module argument/option, include:
+  * If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module option, include:
 
   :option-name:
 
     * Declarative operation (not CRUD), to focus on the final state, for example `online:`, rather than `is_online:`.
     * The name of the option should be consistent with the rest of the module, as well as other modules in the same category.
+    * When in doubt, look for other modules to find option names that are used for the same purpose, we like to offer consistency to our users.
 
   :description:
 
     * Detailed explanation of what this option does. It should be written in full sentences.
-    * Should not list the possible values (that's what ``choices:`` is for, though it should explain `what` the values do if they aren't obvious).
-    * If an optional parameter is sometimes required this need to be reflected in the documentation, e.g. "Required when I(state=present)."
+    * The first entry is a description of the option itself; subsequent entries detail its use, dependencies, or format of possible values.
+    * Should not list the possible values (that's what ``choices:`` is for, though it should explain what the values do if they aren't obvious).
+    * If an option is only sometimes required, describe the conditions. For example, "Required when I(state=present)."
     * Mutually exclusive options must be documented as the final sentence on each of the options.
 
   :required:
@@ -187,8 +196,8 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
   :default:
 
     * If ``required`` is false/missing, ``default`` may be specified (assumed 'null' if missing).
-    * Ensure that the default parameter in the docs matches the default parameter in the code.
-    * The default option must not be listed as part of the description.
+    * Ensure that the default value in the docs matches the default value in the code.
+    * The default field must not be listed as part of the description, unless it requires additional information or conditions.
     * If the option is a boolean value, you can use any of the boolean values recognized by Ansible:
       (such as true/false or yes/no).  Choose the one that reads better in the context of the option.
 
@@ -209,11 +218,11 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
   :version_added:
 
     * Only needed if this option was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
-    * This is a string, and not a float, i.e. ``version_added: "2.3"``.
+    * This is a string, and not a float, i.e. ``version_added: '2.3'``.
 
   :suboptions:
 
-    * If this option takes a dict, you can define it here.
+    * If this option takes a dict, you can define its structure here.
     * See :ref:`azure_rm_securitygroup_module`, :ref:`os_ironic_node_module` for examples.
 
 :requirements:
@@ -221,11 +230,6 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
   * List of requirements (if applicable).
   * Include minimum versions.
 
-:notes:
-
-  * Details of any important information that doesn't fit in one of the above sections.
-  * For example, whether ``check_mode`` is or is not supported.
-
 :seealso:
 
   * A list of references to other modules, documentation or Internet resources
@@ -252,6 +256,11 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
           description: Complete reference of the APIC object model.
           link: https://developer.cisco.com/docs/apic-mim-ref/
 
+:notes:
+
+  * Details of any important information that doesn't fit in one of the above sections.
+  * For example, whether ``check_mode`` is or is not supported.
+
 
 Linking within module documentation
 -----------------------------------
@@ -272,22 +281,22 @@ You can link from your module documentation to other module docs, other resource
 Documentation fragments
 -----------------------
 
-If you're writing multiple related modules, they may share common documentation, such as authentication details or file mode settings. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation.
+If you're writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation.
 
 .. _note:
-  * in 2.8 the Ansible directories for doc fragments changed, see documentation of previous versions to find the old locations.
+  * Prior to Ansible 2.8, documentation fragments were kept in ``lib/ansible/utils/module_docs_fragments``.
 
 .. versionadded:: 2.8
 
-Since version 2.8, you can have user supplied doc_fragments by using a ``doc_fragments`` directory adjacent to play or role, just like any other plugin.
+Since Ansible 2.8, you can have user-supplied doc_fragments by using a ``doc_fragments`` directory adjacent to play or role, just like any other plugin.
 
 For example, all AWS modules should include:
 
 .. code-block:: yaml+jinja
 
     extends_documentation_fragment:
-        - aws
-        - ec2
+    - aws
+    - ec2
 
 
 You can find more examples by searching for ``extends_documentation_fragment`` under the Ansible source tree.
@@ -297,17 +306,21 @@ You can find more examples by searching for ``extends_documentation_fragment`` u
 EXAMPLES block
 ==============
 
-After the shebang, the copyright line, the license, the ``ANSIBLE_METADATA`` section, and the ``DOCUMENTATION`` block comes the ``EXAMPLES`` block. Here you show users how your module works with real-world examples in multi-line plain-text YAML format. The best examples are ready for the user to copy and paste into a playbook. Review and update your examples with every change to your module.
+After the shebang, the UTF-8 coding, the copyright line, the license, the ``ANSIBLE_METADATA`` section, and the ``DOCUMENTATION`` block comes the ``EXAMPLES`` block. Here you show users how your module works with real-world examples in multi-line plain-text YAML format. The best examples are ready for the user to copy and paste into a playbook. Review and update your examples with every change to your module.
 
 Per playbook best practices, each example should include a ``name:`` line::
 
-    EXAMPLES = '''
+    EXAMPLES = r'''
     - name: Ensure foo is installed
       modulename:
         name: foo
         state: present
     '''
 
+The ``name:`` line should be capitalized and not include a trailing dot.
+
+If your examples use boolean options, use yes/no values. Since the documentation generates boolean values as yes/no, having the examples use these values as well makes the module documentation more consistent.
+
 If your module returns facts that are often needed, an example of how to use them can be helpful.
 
 .. _return_block:
@@ -315,16 +328,16 @@ If your module returns facts that are often needed, an example of how to use the
 RETURN block
 ============
 
-After the shebang, the copyright line, the license, the ``ANSIBLE_METADATA`` section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.
+After the shebang, the UTF-8 coding, the copyright line, the license, the ``ANSIBLE_METADATA`` section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.
 
-If your module doesn't return anything (apart from the standard returns), this section of your module should read: ``RETURN = ''' # '''``
+If your module doesn't return anything (apart from the standard returns), this section of your module should read: ``RETURN = r''' # '''``
 Otherwise, for each value returned, provide the following fields. All fields are required unless specified otherwise.
 
 :return name:
   Name of the returned field.
 
   :description:
-    Detailed description of what this value represents.
+    Detailed description of what this value represents. Capitalized and with trailing dot.
   :returned:
     When this value is returned, such as ``always``, or ``on success``.
   :type:
@@ -333,31 +346,31 @@ Otherwise, for each value returned, provide the following fields. All fields are
     One or more examples.
   :version_added:
     Only needed if this return was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
-    This is a string, and not a float, i.e. ``version_added: "2.3"``.
+    This is a string, and not a float, i.e. ``version_added: '2.3'``.
   :contains:
     Optional. To describe nested return values, set ``type: complex`` and repeat the elements above for each sub-field.
 
 Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field::
 
-    RETURN = '''
+    RETURN = r'''
     dest:
-        description: destination file/path
+        description: Destination file/path.
         returned: success
-        type: string
+        type: str
         sample: /path/to/file.txt
     src:
-        description: source file used for the copy on the target machine
+        description: Source file used for the copy on the target machine.
         returned: changed
-        type: string
+        type: str
         sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
     md5sum:
-        description: md5 checksum of the file after running copy
+        description: MD5 checksum of the file after running copy.
         returned: when supported
-        type: string
+        type: str
         sample: 2a5aeecc61dc98c4d780b14b330e3282
     '''
 
-    RETURN = '''
+    RETURN = r'''
     packages:
         description: Information about package requirements
         returned: On success
@@ -385,7 +398,7 @@ Here are two example ``RETURN`` sections, one with three simple fields and one w
 Python imports
 ==============
 
-After the shebang, the copyright line, the license, and the sections for ``ANSIBLE_METADATA``, ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN``, you can finally add the python imports. All modules must use Python imports in the form:
+After the shebang, the UTF-8 coding, the copyright line, the license, and the sections for ``ANSIBLE_METADATA``, ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN``, you can finally add the python imports. All modules must use Python imports in the form:
 
 .. code-block:: python
 

docs/docsite/rst/dev_guide/developing_modules_general.rst

@@ -307,5 +307,5 @@ use the ``#ansible`` channel.
 Credit
 ======
 
-Thank you to Thomas Stringer (`@tstringer <https://github.com/tstringer>`_) for contributing source
+Thank you to Thomas Stringer (`@trstringer <https://github.com/trstringer>`_) for contributing source
 material for this topic.

docs/docsite/rst/dev_guide/developing_modules_in_groups.rst

@@ -91,7 +91,6 @@ The first PR should include the following files:
 * ``lib/ansible/modules/$category/$topic/$yourfirstmodule.py`` - A single module. *Required new file*
 * ``lib/ansible/plugins/doc_fragments/$topic.py`` - Code documentation, such as details regarding common arguments. *Optional new file*
 * ``lib/ansible/module_utils/$topic.py`` - Code shared between more than one module, such as common arguments. *Optional new file*
-*  ``docs/docsite/rst/dev_guide/developing_module_utilities.rst`` - Document your new `module_utils` file. *Optional update to existing file*
 
 And that's it.
 

docs/docsite/rst/dev_guide/developing_program_flow_modules.rst

@@ -5,13 +5,9 @@
 Ansible module architecture
 ***************************
 
-This in-depth dive helps you understand Ansible's program flow to execute
-modules. It is written for people working on the portions of the Core Ansible
-Engine that execute a module. Those writing Ansible Modules may also find this
-in-depth dive to be of interest, but individuals simply using Ansible Modules
-will not likely find this to be helpful.
+If you're working on Ansible's Core code, writing an Ansible module, or developing an action plugin, this deep dive helps you understand how Ansible's program flow executes. If you're just using Ansible Modules in playbooks, you can skip this section.
 
-.. contents:: Topics
+.. contents::
    :local:
 
 .. _flow_types_of_modules:
@@ -19,7 +15,7 @@ will not likely find this to be helpful.
 Types of modules
 ================
 
-Ansible supports several different types of modules in its code base.  Some of
+Ansible supports several different types of modules in its code base. Some of
 these are for backwards compatibility and others are to enable flexibility.
 
 .. _flow_action_plugins:
@@ -27,20 +23,18 @@ these are for backwards compatibility and others are to enable flexibility.
 Action plugins
 --------------
 
-Action Plugins look like modules to end users who are writing :term:`playbooks` but
-they're distinct entities for the purposes of this document.  Action Plugins
-always execute on the controller and are sometimes able to do all work there
-(for instance, the ``debug`` Action Plugin which prints some text for the user to
-see or the ``assert`` Action Plugin which can test whether several values in
-a playbook satisfy certain criteria.)
+Action plugins look like modules to anyone writing a playbook. Usage documentation for most action plugins lives inside a module of the same name. Some action plugins do all the work, with the module providing only documentation. Some action plugins execute modules. The ``normal`` action plugin executes modules that don't have special action plugins. Action plugins always execute on the controller.
 
-More often, Action Plugins set up some values on the controller, then invoke an
-actual module on the managed node that does something with these values.  An
-easy to understand version of this is the :ref:`template Action Plugin
-<template_module>`.  The :ref:`template Action Plugin <template_module>` takes values from
+Some action plugins do all their work on the controller. For
+example, the :ref:`debug <debug_module>` action plugin (which prints text for
+the user to see) and the :ref:`assert <assert_module>` action plugin (which
+tests whether values in a playbook satisfy certain criteria) execute entirely on the controller.
+
+Most action plugins set up some values on the controller, then invoke an
+actual module on the managed node that does something with these values. For example, the :ref:`template <template_module>` action plugin takes values from
 the user to construct a file in a temporary location on the controller using
-variables from the playbook environment.  It then transfers the temporary file
-to a temporary file on the remote system.  After that, it invokes the
+variables from the playbook environment. It then transfers the temporary file
+to a temporary file on the remote system. After that, it invokes the
 :ref:`copy module <copy_module>` which operates on the remote system to move the file
 into its final location, sets file permissions, and so on.
 
@@ -49,23 +43,20 @@ into its final location, sets file permissions, and so on.
 New-style modules
 -----------------
 
-All of the modules that ship with Ansible fall into this category.
+All of the modules that ship with Ansible fall into this category. While you can write modules in any language, all official modules (shipped with Ansible) use either Python or PowerShell.
 
 New-style modules have the arguments to the module embedded inside of them in
-some manner.  Non-new-style modules must copy a separate file over to the
+some manner. Old-style modules must copy a separate file over to the
 managed node, which is less efficient as it requires two over-the-wire
 connections instead of only one.
 
 .. _flow_python_modules:
 
 Python
-------
+^^^^^^
 
 New-style Python modules use the :ref:`Ansiballz` framework for constructing
-modules.  All official modules (shipped with Ansible) use either this or the
-:ref:`powershell module framework <flow_powershell_modules>`.
-
-These modules use imports from :code:`ansible.module_utils` in order to pull in
+modules. These modules use imports from :code:`ansible.module_utils` to pull in
 boilerplate module code, such as argument parsing, formatting of return
 values as :term:`JSON`, and various file operations.
 
@@ -76,21 +67,21 @@ values as :term:`JSON`, and various file operations.
 
 .. _flow_powershell_modules:
 
-Powershell
-----------
+PowerShell
+^^^^^^^^^^
 
-New-style powershell modules use the :ref:`module_replacer` framework for
-constructing modules.  These modules get a library of powershell code embedded
+New-style PowerShell modules use the :ref:`module_replacer` framework for
+constructing modules. These modules get a library of PowerShell code embedded
 in them before being sent to the managed node.
 
 .. _flow_jsonargs_modules:
 
-JSONARGS
---------
+JSONARGS modules
+----------------
 
-Scripts can arrange for an argument string to be placed within them by placing
-the string ``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` somewhere inside of the
-file.  The module typically sets a variable to that value like this:
+These modules are scripts that include the string
+``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` in their body.
+This string is replaced with the JSON-formatted argument string. These modules typically set a variable to that value like this:
 
 .. code-block:: python
 
@@ -102,20 +93,20 @@ Which is expanded as:
 
     json_arguments = """{"param1": "test's quotes", "param2": "\"To be or not to be\" - Hamlet"}"""
 
-.. note:: Ansible outputs a :term:`JSON` string with bare quotes.  Double quotes are
+.. note:: Ansible outputs a :term:`JSON` string with bare quotes. Double quotes are
        used to quote string values, double quotes inside of string values are
        backslash escaped, and single quotes may appear unescaped inside of
-       a string value.  To use JSONARGS, your scripting language must have a way
-       to handle this type of string.  The example uses Python's triple quoted
-       strings to do this.  Other scripting languages may have a similar quote
+       a string value. To use JSONARGS, your scripting language must have a way
+       to handle this type of string. The example uses Python's triple quoted
+       strings to do this. Other scripting languages may have a similar quote
        character that won't be confused by any quotes in the JSON or it may
        allow you to define your own start-of-quote and end-of-quote characters.
        If the language doesn't give you any of these then you'll need to write
        a :ref:`non-native JSON module <flow_want_json_modules>` or
        :ref:`Old-style module <flow_old_style_modules>` instead.
 
-The module typically parses the contents of ``json_arguments`` using a JSON
-library and then use them as native variables throughout the rest of its code.
+These modules typically parse the contents of ``json_arguments`` using a JSON
+library and then use them as native variables throughout the code.
 
 .. _flow_want_json_modules:
 
@@ -124,12 +115,12 @@ Non-native want JSON modules
 
 If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats
 it as a non-native module that accepts a filename as its only command line
-parameter.  The filename is for a temporary file containing a :term:`JSON`
-string containing the module's parameters.  The module needs to open the file,
+parameter. The filename is for a temporary file containing a :term:`JSON`
+string containing the module's parameters. The module needs to open the file,
 read and parse the parameters, operate on the data, and print its return data
 as a JSON encoded dictionary to stdout before exiting.
 
-These types of modules are self-contained entities.  As of Ansible 2.1, Ansible
+These types of modules are self-contained entities. As of Ansible 2.1, Ansible
 only modifies them to change a shebang line if present.
 
 .. seealso:: Examples of Non-native modules written in ruby are in the `Ansible
@@ -140,14 +131,14 @@ only modifies them to change a shebang line if present.
 Binary modules
 --------------
 
-From Ansible 2.2 onwards, modules may also be small binary programs.  Ansible
+From Ansible 2.2 onwards, modules may also be small binary programs. Ansible
 doesn't perform any magic to make these portable to different systems so they
 may be specific to the system on which they were compiled or require other
-binary runtime dependencies.  Despite these drawbacks, a site may sometimes
-have no choice but to compile a custom module against a specific binary
-library if that's the only way they have to get access to certain resources.
+binary runtime dependencies. Despite these drawbacks, you may have
+to compile a custom module against a specific binary
+library if that's the only way to get access to certain resources.
 
-Binary modules take their arguments and will return data to Ansible in the same
+Binary modules take their arguments and return data to Ansible in the same
 way as :ref:`want JSON modules <flow_want_json_modules>`.
 
 .. seealso:: One example of a `binary module
@@ -162,10 +153,8 @@ Old-style modules
 Old-style modules are similar to
 :ref:`want JSON modules <flow_want_json_modules>`, except that the file that
 they take contains ``key=value`` pairs for their parameters instead of
-:term:`JSON`.
-
-Ansible decides that a module is old-style when it doesn't have any of the
-markers that would show that it is one of the other types.
+:term:`JSON`. Ansible decides that a module is old-style when it doesn't have
+any of the markers that would show that it is one of the other types.
 
 .. _flow_how_modules_are_executed:
 
@@ -173,8 +162,8 @@ How modules are executed
 ========================
 
 When a user uses :program:`ansible` or :program:`ansible-playbook`, they
-specify a task to execute.  The task is usually the name of a module along
-with several parameters to be passed to the module.  Ansible takes these
+specify a task to execute. The task is usually the name of a module along
+with several parameters to be passed to the module. Ansible takes these
 values and processes them in various ways before they are finally executed on
 the remote machine.
 
@@ -185,44 +174,43 @@ Executor/task_executor
 
 The TaskExecutor receives the module name and parameters that were parsed from
 the :term:`playbook <playbooks>` (or from the command line in the case of
-:command:`/usr/bin/ansible`).  It uses the name to decide whether it's looking
-at a module or an :ref:`Action Plugin <flow_action_plugins>`.  If it's
+:command:`/usr/bin/ansible`). It uses the name to decide whether it's looking
+at a module or an :ref:`Action Plugin <flow_action_plugins>`. If it's
 a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>`
 and passes the name, variables, and other information about the task and play
 to that Action Plugin for further processing.
 
 .. _flow_normal_action_plugin:
 
-Normal action plugin
---------------------
+The ``normal`` action plugin
+----------------------------
 
-The ``normal`` action plugin executes the module on the remote host.  It is
+The ``normal`` action plugin executes the module on the remote host. It is
 the primary coordinator of much of the work to actually execute the module on
 the managed machine.
 
-* It takes care of creating a connection to the managed machine by
-  instantiating a ``Connection`` class according to the inventory
-  configuration for that host.
-* It adds any internal Ansible variables to the module's parameters (for
+* It loads the appropriate connection plugin for the task, which then transfers
+  or executes as needed to create a connection to that host.
+* It adds any internal Ansible properties to the module's parameters (for
   instance, the ones that pass along ``no_log`` to the module).
-* It takes care of creating any temporary files on the remote machine and
+* It works with other plugins (connection, shell, become, other action plugins)
+  to create any temporary files on the remote machine and
   cleans up afterwards.
-* It does the actual work of pushing the module and module parameters to the
+* It pushes the module and module parameters to the
   remote host, although the :ref:`module_common <flow_executor_module_common>`
-  code described in the next section does the work of deciding which format
+  code described in the next section decides which format
   those will take.
-* It handles any special cases regarding modules (for instance, various
-  complications around Windows modules that must have the same names as Python
-  modules, so that internal calling of modules from other Action Plugins work.)
+* It handles any special cases regarding modules (for instance, async
+  execution, or complications around Windows modules that must have the same names as Python modules, so that internal calling of modules from other Action Plugins work.)
 
 Much of this functionality comes from the `BaseAction` class,
-which lives in :file:`plugins/action/__init__.py`.  It makes use of
+which lives in :file:`plugins/action/__init__.py`. It uses the
 ``Connection`` and ``Shell`` objects to do its work.
 
 .. note::
     When :term:`tasks <tasks>` are run with the ``async:`` parameter, Ansible
     uses the ``async`` Action Plugin instead of the ``normal`` Action Plugin
-    to invoke it.  That program flow is currently not documented.  Read the
+    to invoke it. That program flow is currently not documented. Read the
     source for information on how that works.
 
 .. _flow_executor_module_common:
@@ -230,25 +218,27 @@ which lives in :file:`plugins/action/__init__.py`.  It makes use of
 Executor/module_common.py
 -------------------------
 
-Code in :file:`executor/module_common.py` takes care of assembling the module
-to be shipped to the managed node.  The module is first read in, then examined
-to determine its type.  :ref:`PowerShell <flow_powershell_modules>` and
-:ref:`JSON-args modules <flow_jsonargs_modules>` are passed through
-:ref:`Module Replacer <module_replacer>`.  New-style
-:ref:`Python modules <flow_python_modules>` are assembled by :ref:`Ansiballz`.
-:ref:`Non-native-want-JSON <flow_want_json_modules>`,
-:ref:`Binary modules <flow_binary_modules>`, and
-:ref:`Old-Style modules <flow_old_style_modules>` aren't touched by either of
-these and pass through unchanged.  After the assembling step, one final
-modification is made to all modules that have a shebang line.  Ansible checks
+Code in :file:`executor/module_common.py` assembles the module
+to be shipped to the managed node. The module is first read in, then examined
+to determine its type:
+
+* :ref:`PowerShell <flow_powershell_modules>` and :ref:`JSON-args modules <flow_jsonargs_modules>` are passed through :ref:`Module Replacer <module_replacer>`.
+* New-style :ref:`Python modules <flow_python_modules>` are assembled by :ref:`Ansiballz`.
+* :ref:`Non-native-want-JSON <flow_want_json_modules>`, :ref:`Binary modules <flow_binary_modules>`, and :ref:`Old-Style modules <flow_old_style_modules>` aren't touched by either of these and pass through unchanged.
+
+After the assembling step, one final
+modification is made to all modules that have a shebang line. Ansible checks
 whether the interpreter in the shebang line has a specific path configured via
-an ``ansible_$X_interpreter`` inventory variable.  If it does, Ansible
-substitutes that path for the interpreter path given in the module.  After
+an ``ansible_$X_interpreter`` inventory variable. If it does, Ansible
+substitutes that path for the interpreter path given in the module. After
 this, Ansible returns the complete module data and the module type to the
 :ref:`Normal Action <flow_normal_action_plugin>` which continues execution of
 the module.
 
-Next we'll go into some details of the two assembler frameworks.
+Assembler frameworks
+--------------------
+
+Ansible supports two assembler frameworks: Ansiballz and the older Module Replacer.
 
 .. _module_replacer:
 
@@ -256,12 +246,12 @@ Module Replacer framework
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The Module Replacer framework is the original framework implementing new-style
-modules.  It is essentially a preprocessor (like the C Preprocessor for those
-familiar with that programming language).  It does straight substitutions of
-specific substring patterns in the module file.  There are two types of
+modules, and is still used for PowerShell modules. It is essentially a preprocessor (like the C Preprocessor for those
+familiar with that programming language). It does straight substitutions of
+specific substring patterns in the module file. There are two types of
 substitutions:
 
-* Replacements that only happen in the module file.  These are public
+* Replacements that only happen in the module file. These are public
   replacement strings that modules can utilize to get helpful boilerplate or
   access to arguments.
 
@@ -272,12 +262,10 @@ substitutions:
     :code:`from ansible.module_utils.basic import *` and should also only apply
     to new-style Python modules.
   - :code:`# POWERSHELL_COMMON` substitutes the contents of
-    :file:`ansible/module_utils/powershell.ps1`.  It should only be used with
+    :file:`ansible/module_utils/powershell.ps1`. It should only be used with
     :ref:`new-style Powershell modules <flow_powershell_modules>`.
 
-* Replacements that are used by ``ansible.module_utils`` code.  These are internal
-  replacement patterns.  They may be used internally, in the above public
-  replacements, but shouldn't be used directly by modules.
+* Replacements that are used by ``ansible.module_utils`` code. These are internal replacement patterns. They may be used internally, in the above public replacements, but shouldn't be used directly by modules.
 
   - :code:`"<<ANSIBLE_VERSION>>"` is substituted with the Ansible version.  In
     :ref:`new-style Python modules <flow_python_modules>` under the
@@ -286,29 +274,29 @@ substitutions:
     :attr:``AnsibleModule.ansible_version``.
   - :code:`"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>"` is substituted with
     a string which is the Python ``repr`` of the :term:`JSON` encoded module
-    parameters.  Using ``repr`` on the JSON string makes it safe to embed in
-    a Python file.  In new-style Python modules under the Ansiballz framework
+    parameters. Using ``repr`` on the JSON string makes it safe to embed in
+    a Python file. In new-style Python modules under the Ansiballz framework
     this is better accessed by instantiating an `AnsibleModule` and
     then using :attr:`AnsibleModule.params`.
   - :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is
     a comma separated list of file systems which have a file system dependent
-    security context in SELinux.  In new-style Python modules, if you really
+    security context in SELinux. In new-style Python modules, if you really
     need this you should instantiate an `AnsibleModule` and then use
-    :attr:`AnsibleModule._selinux_special_fs`.  The variable has also changed
+    :attr:`AnsibleModule._selinux_special_fs`. The variable has also changed
     from a comma separated string of file system names to an actual python
     list of filesystem names.
   - :code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module
-    parameters as a JSON string.  Care must be taken to properly quote the
-    string as JSON data may contain quotes.  This pattern is not substituted
+    parameters as a JSON string. Care must be taken to properly quote the
+    string as JSON data may contain quotes. This pattern is not substituted
     in new-style Python modules as they can get the module parameters another
     way.
   - The string :code:`syslog.LOG_USER` is replaced wherever it occurs with the
     ``syslog_facility`` which was named in :file:`ansible.cfg` or any
     ``ansible_syslog_facility`` inventory variable that applies to this host.  In
-    new-style Python modules this has changed slightly.  If you really need to
+    new-style Python modules this has changed slightly. If you really need to
     access it, you should instantiate an `AnsibleModule` and then use
-    :attr:`AnsibleModule._syslog_facility` to access it.  It is no longer the
-    actual syslog facility and is now the name of the syslog facility.  See
+    :attr:`AnsibleModule._syslog_facility` to access it. It is no longer the
+    actual syslog facility and is now the name of the syslog facility. See
     the :ref:`documentation on internal arguments <flow_internal_arguments>`
     for details.
 
@@ -317,32 +305,36 @@ substitutions:
 Ansiballz framework
 ^^^^^^^^^^^^^^^^^^^
 
-Ansible 2.1 switched from the :ref:`module_replacer` framework to the
-Ansiballz framework for assembling modules.  The Ansiballz framework differs
-from module replacer in that it uses real Python imports of things in
-:file:`ansible/module_utils` instead of merely preprocessing the module.  It
+The Ansiballz framework was adopted in Ansible 2.1 and is used for all new-style Python modules. Unlike the Module Replacer, Ansiballz uses real Python imports of things in
+:file:`ansible/module_utils` instead of merely preprocessing the module. It
 does this by constructing a zipfile -- which includes the module file, files
 in :file:`ansible/module_utils` that are imported by the module, and some
-boilerplate to pass in the module's parameters.  The zipfile is then Base64
+boilerplate to pass in the module's parameters. The zipfile is then Base64
 encoded and wrapped in a small Python script which decodes the Base64 encoding
-and places the zipfile into a temp directory on the managed node.  It then
-extracts just the ansible module script from the zip file and places that in
-the temporary directory as well.  Then it sets the PYTHONPATH to find python
-modules inside of the zip file and invokes :command:`python` on the extracted
-ansible module.
+and places the zipfile into a temp directory on the managed node. It then
+extracts just the Ansible module script from the zip file and places that in
+the temporary directory as well. Then it sets the PYTHONPATH to find Python
+modules inside of the zip file and imports the Ansible module as the special name, ``__main__``.
+Importing it as ``__main__`` causes Python to think that it is executing a script rather than simply
+importing a module. This lets Ansible run both the wrapper script and the module code in a single copy of Python on the remote machine.
 
 .. note::
-    Ansible wraps the zipfile in the Python script for two reasons:
+    * Ansible wraps the zipfile in the Python script for two reasons:
 
-    * for compatibility with Python 2.6 which has a less
-      functional version of Python's ``-m`` command line switch.
-    * so that pipelining will function properly.  Pipelining needs to pipe the
-      Python module into the Python interpreter on the remote node.  Python
-      understands scripts on stdin but does not understand zip files.
+        * for compatibility with Python 2.6 which has a less
+          functional version of Python's ``-m`` command line switch.
+
+        * so that pipelining will function properly. Pipelining needs to pipe the
+          Python module into the Python interpreter on the remote node. Python
+          understands scripts on stdin but does not understand zip files.
+
+    * Prior to Ansible 2.7, the module was executed via a second Python interpreter instead of being
+      executed inside of the same process. This change was made once Python-2.4 support was dropped
+      to speed up module execution.
 
 In Ansiballz, any imports of Python modules from the
 :py:mod:`ansible.module_utils` package trigger inclusion of that Python file
-into the zipfile.  Instances of :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` in
+into the zipfile. Instances of :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` in
 the module are turned into :code:`from ansible.module_utils.basic import *`
 and :file:`ansible/module-utils/basic.py` is then included in the zipfile.
 Files that are included from :file:`module_utils` are themselves scanned for
@@ -351,34 +343,34 @@ the zipfile as well.
 
 .. warning::
     At present, the Ansiballz Framework cannot determine whether an import
-    should be included if it is a relative import.  Always use an absolute
+    should be included if it is a relative import. Always use an absolute
     import that has :py:mod:`ansible.module_utils` in it to allow Ansiballz to
     determine that the file should be included.
 
+
 .. _flow_passing_module_args:
 
 Passing args
 ------------
 
-In :ref:`module_replacer`, module arguments are turned into a JSON-ified
-string and substituted into the combined module file.  In :ref:`Ansiballz`,
-the JSON-ified string is passed into the module via stdin.  When
-a  :class:`ansible.module_utils.basic.AnsibleModule` is instantiated,
-it parses this string and places the args into
-:attr:`AnsibleModule.params` where it can be accessed by the module's
-other code.
+Arguments are passed differently by the two frameworks:
+
+* In :ref:`module_replacer`, module arguments are turned into a JSON-ified string and substituted into the combined module file.
+* In :ref:`Ansiballz`, the JSON-ified string is part of the script which wraps the zipfile. Just before the wrapper script imports the Ansible module as ``__main__``, it monkey-patches the private, ``_ANSIBLE_ARGS`` variable in ``basic.py`` with the variable values. When a :class:`ansible.module_utils.basic.AnsibleModule` is instantiated, it parses this string and places the args into :attr:`AnsibleModule.params` where it can be accessed by the module's other code.
+
+.. warning::
+    If you are writing modules, remember that the way we pass arguments is an internal implementation detail: it has changed in the past and will change again as soon as changes to the common module_utils
+    code allow Ansible modules to forgo using :class:`ansible.module_utils.basic.AnsibleModule`. Do not rely on the internal global ``_ANSIBLE_ARGS`` variable.
+
+    Very dynamic custom modules which need to parse arguments before they
+    instantiate an ``AnsibleModule`` may use ``_load_params`` to retrieve those parameters.
+    Although ``_load_params`` may change in breaking ways if necessary to support
+    changes in the code, it is likely to be more stable than either the way we pass parameters or the internal global variable.
 
 .. note::
-    Internally, the `AnsibleModule` uses the helper function,
-    :py:func:`ansible.module_utils.basic._load_params`, to load the parameters
-    from stdin and save them into an internal global variable.  Very dynamic
-    custom modules which need to parse the parameters prior to instantiating
-    an ``AnsibleModule`` may use ``_load_params`` to retrieve the
-    parameters.  Be aware that ``_load_params`` is an internal function and
-    may change in breaking ways if necessary to support changes in the code.
-    However, we'll do our best not to break it gratuitously, which is not
-    something that can be said for either the way parameters are passed or
-    the internal global variable.
+    Prior to Ansible 2.7, the Ansible module was invoked in a second Python interpreter and the
+    arguments were then passed to the script over the script's stdin.
+
 
 .. _flow_internal_arguments:
 
@@ -386,93 +378,85 @@ Internal arguments
 ------------------
 
 Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to
-the module beyond those which the user specified in the playbook.  These
+the module beyond those which the user specified in the playbook. These
 additional arguments are internal parameters that help implement global
-Ansible features.  Modules often do not need to know about these explicitly as
+Ansible features. Modules often do not need to know about these explicitly as
 the features are implemented in :py:mod:`ansible.module_utils.basic` but certain
 features need support from the module so it's good to know about them.
 
+The internal arguments listed here are global. If you need to add a local internal argument to a custom module, create an action plugin for that specific module - see ``_original_basename`` in the `copy action plugin <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an example.
+
 _ansible_no_log
 ^^^^^^^^^^^^^^^
 
-This is a boolean.  If it's True then the playbook specified ``no_log`` (in
-a task's parameters or as a play parameter).  This automatically affects calls
-to :py:meth:`AnsibleModule.log`.  If a module implements its own logging then
-it needs to check this value.  The best way to look at this is for the module
-to instantiate an `AnsibleModule` and then check the value of
-:attr:`AnsibleModule.no_log`.
+Boolean. Set to True whenever a parameter in a task or play specifies ``no_log``. Any module that calls :py:meth:`AnsibleModule.log` handles this automatically. If a module implements its own logging then
+it needs to check this value. To access in a module, instantiate an
+``AnsibleModule`` and then check the value of :attr:`AnsibleModule.no_log`.
 
 .. note::
-    ``no_log`` specified in a module's argument_spec are handled by a different mechanism.
+    ``no_log`` specified in a module's argument_spec is handled by a different mechanism.
 
 _ansible_debug
 ^^^^^^^^^^^^^^^
 
-This is a boolean that turns on more verbose logging.  If a module uses
+Boolean. Turns more verbose logging on or off and turns on logging of
+external commands that the module executes. If a module uses
 :py:meth:`AnsibleModule.debug` rather than :py:meth:`AnsibleModule.log` then
-the messages are only logged if this is True.  This also turns on logging of
-external commands that the module executes.  This can be changed via
-the ``debug`` setting in :file:`ansible.cfg` or the environment variable
-:envvar:`ANSIBLE_DEBUG`.  If, for some reason, a module must access this, it
-should do so by instantiating an `AnsibleModule` and accessing
-:attr:`AnsibleModule._debug`.
+the messages are only logged if ``_ansible_debug`` is set to ``True``.
+To set, add ``debug: True`` to :file:`ansible.cfg` or set the environment
+variable :envvar:`ANSIBLE_DEBUG`. To access in a module, instantiate an
+``AnsibleModule`` and access :attr:`AnsibleModule._debug`.
 
 _ansible_diff
 ^^^^^^^^^^^^^^^
 
-This boolean is turned on via the ``--diff`` command line option.  If a module
-supports it, it will tell the module to show a unified diff of changes to be
-made to templated files.  The proper way for a module to access this is by
-instantiating an `AnsibleModule` and accessing
+Boolean. If a module supports it, tells the module to show a unified diff of
+changes to be made to templated files. To set, pass the ``--diff`` command line
+option. To access in a module, instantiate an `AnsibleModule` and access
 :attr:`AnsibleModule._diff`.
 
 _ansible_verbosity
 ^^^^^^^^^^^^^^^^^^
 
-This value could be used for finer grained control over logging. However, it
-is currently unused.
+Unused. This value could be used for finer grained control over logging.
 
 _ansible_selinux_special_fs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is a list of names of filesystems which should have a special selinux
-context.  They are used by the `AnsibleModule` methods which operate on
-files (changing attributes, moving, and copying).  The list of names is set
-via a comma separated string of filesystem names from :file:`ansible.cfg`::
+List. Names of filesystems which should have a special SELinux
+context. They are used by the `AnsibleModule` methods which operate on
+files (changing attributes, moving, and copying). To set, add a comma separated string of filesystem names in :file:`ansible.cfg`::
 
   # ansible.cfg
   [selinux]
   special_context_filesystems=nfs,vboxsf,fuse,ramfs
 
-If a module cannot use the builtin ``AnsibleModule`` methods to manipulate
-files and needs to know about these special context filesystems, it should
-instantiate an ``AnsibleModule`` and then examine the list in
+Most modules can use the built-in ``AnsibleModule`` methods to manipulate
+files. To access in a module that needs to know about these special context filesystems, instantiate an ``AnsibleModule`` and examine the list in
 :attr:`AnsibleModule._selinux_special_fs`.
 
 This replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from
-:ref:`module_replacer`.  In module replacer it was a comma separated string of
-filesystem names.  Under Ansiballz it's an actual list.
+:ref:`module_replacer`. In module replacer it was a comma separated string of
+filesystem names. Under Ansiballz it's an actual list.
 
 .. versionadded:: 2.1
 
 _ansible_syslog_facility
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-This parameter controls which syslog facility ansible module logs to.  It may
-be set by changing the ``syslog_facility`` value in :file:`ansible.cfg`.  Most
+This parameter controls which syslog facility Ansible module logs to. To set, change the ``syslog_facility`` value in :file:`ansible.cfg`. Most
 modules should just use :meth:`AnsibleModule.log` which will then make use of
-this.  If a module has to use this on its own, it should instantiate an
+this. If a module has to use this on its own, it should instantiate an
 `AnsibleModule` and then retrieve the name of the syslog facility from
-:attr:`AnsibleModule._syslog_facility`.  The code will look slightly different
-than it did under :ref:`module_replacer` due to how hacky the old way was
+:attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less hacky than the old :ref:`module_replacer` code:
 
 .. code-block:: python
 
-        # Old way
+        # Old module_replacer way
         import syslog
         syslog.openlog(NAME, 0, syslog.LOG_USER)
 
-        # New way
+        # New Ansiballz way
         import syslog
         facility_name = module._syslog_facility
         facility = getattr(syslog, facility_name, syslog.LOG_USER)
@@ -483,14 +467,29 @@ than it did under :ref:`module_replacer` due to how hacky the old way was
 _ansible_version
 ^^^^^^^^^^^^^^^^
 
-This parameter passes the version of ansible that runs the module.  To access
+This parameter passes the version of Ansible that runs the module. To access
 it, a module should instantiate an `AnsibleModule` and then retrieve it
-from :attr:`AnsibleModule.ansible_version`.  This replaces
+from :attr:`AnsibleModule.ansible_version`. This replaces
 :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from
 :ref:`module_replacer`.
 
 .. versionadded:: 2.1
 
+
+.. _flow_module_return_values:
+
+Module return values & Unsafe strings
+-------------------------------------
+
+At the end of a module's execution, it formats the data that it wants to return as a JSON string and prints the string to its stdout. The normal action plugin receives the JSON string, parses it into a Python dictionary, and returns it to the executor.
+
+If Ansible templated every string return value, it would be vulnerable to an attack from users with access to managed nodes. If an unscrupulous user disguised malicious code as Ansible return value strings, and if those strings were then templated on the controller, Ansible could execute arbitrary code. To prevent this scenario, Ansible marks all strings inside returned data as ``Unsafe``, emitting any Jinja2 templates in the strings verbatim, not expanded by Jinja2.
+
+Strings returned by invoking a module through ``ActionPlugin._execute_module()`` are automatically marked as ``Unsafe`` by the normal action plugin. If another action plugin retrieves information from a module through some other means, it must mark its return data as ``Unsafe`` on its own.
+
+In case a poorly-coded action plugin fails to mark its results as "Unsafe," Ansible audits the results again when they are returned to the executor,
+marking all strings as ``Unsafe``. The normal action plugin protects itself and any other code that it calls with the result data as a parameter. The check inside the executor protects the output of all other action plugins, ensuring that subsequent tasks run by Ansible will not template anything from those results either.
+
 .. _flow_special_considerations:
 
 Special considerations
@@ -510,7 +509,7 @@ Ansible can transfer a module to a remote machine in one of two ways:
   into the remote interpreter's stdin.
 
 Pipelining only works with modules written in Python at this time because
-Ansible only knows that Python supports this mode of operation.  Supporting
+Ansible only knows that Python supports this mode of operation. Supporting
 pipelining means that whatever format the module payload takes before being
 sent over the wire must be executable by Python via stdin.
 
@@ -522,13 +521,13 @@ Why pass args over stdin?
 Passing arguments via stdin was chosen for the following reasons:
 
 * When combined with :ref:`ANSIBLE_PIPELINING`, this keeps the module's arguments from
-  temporarily being saved onto disk on the remote machine.  This makes it
+  temporarily being saved onto disk on the remote machine. This makes it
   harder (but not impossible) for a malicious user on the remote machine to
   steal any sensitive information that may be present in the arguments.
 * Command line arguments would be insecure as most systems allow unprivileged
   users to read the full commandline of a process.
 * Environment variables are usually more secure than the commandline but some
-  systems limit the total size of the environment.  This could lead to
+  systems limit the total size of the environment. This could lead to
   truncation of the parameters if we hit that limit.
 
 

docs/docsite/rst/dev_guide/index.rst

@@ -22,6 +22,7 @@ Find the task that best describes what you want to do:
    * What do I need to know before I start coding?
    * I want to :ref:`set up my Python development environment <environment_setup>`.
    * I want to :ref:`get started writing a module <developing_modules_general>`.
+   * I want to :ref:`write a network module <developing_modules_network>`.
    * I want to :ref:`write a Windows module <developing_modules_general_windows>`.
    * I want to `write an Amazon module <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/amazon/GUIDELINES.md>`_.
    * I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, etc.).
@@ -31,6 +32,7 @@ Find the task that best describes what you want to do:
    * I want to :ref:`debug my module code <debugging>`.
    * I want to :ref:`add tests <developing_testing>`.
    * I want to :ref:`document my module <module_documenting>`.
+   * I want to follow :ref:`conventions and tips for clean, usable module code <developing_modules_best_practices>`.
    * I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.
 
 * I want to work on other development projects:

docs/docsite/rst/dev_guide/overview_architecture.rst

@@ -1,5 +1,5 @@
 ********************
-Ansible Architecture
+Ansible architecture
 ********************
 
 Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs.
@@ -10,26 +10,35 @@ It uses no agents and no additional custom security infrastructure, so it's easy
 
 In this section, we'll give you a really quick overview of how Ansible works so you can see how the pieces fit together.
 
+.. contents::
+   :local:
+
 Modules
 =======
 
-Ansible works by connecting to your nodes and pushing out small programs, called "Ansible Modules" to them. These programs are written to be resource models of the desired state of the system. Ansible then executes these modules (over SSH by default), and removes them when finished.
+Ansible works by connecting to your nodes and pushing out scripts called "Ansible modules" to them. Most modules accept parameters that describe the desired state of the system.
+Ansible then executes these modules (over SSH by default), and removes them when finished. Your library of modules can reside on any machine, and there are no servers, daemons, or databases required.
 
-Your library of modules can reside on any machine, and there are no servers, daemons, or databases required. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content.
+You can :ref:`write your own modules <developing_modules_general>`, though you should first consider :ref:`whether you should <developing_modules>`. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, etc).
+
+Module utilities
+================
+
+When multiple modules use the same code, Ansible stores those functions as module utilities to minimize duplication and maintenance. For example, the code that parses URLs is ``lib/ansible/module_utils/url.py``. You can :ref:`write your own module utilities <developing_module_utilities>` as well. Module utilities may only be written in Python or in PowerShell.
 
 Plugins
 =======
 
-Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own.
+:ref:`Plugins <plugins_lookup>` augment Ansible's core functionality. While modules execute on the target system in separate processes (usually that means on a remote system), plugins execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more. Ansible ships with a number of handy plugins, and you can easily :ref:`write your own <developing_plugins>`. For example, you can write an :ref:`inventory plugin <developing_inventory>` to connect to any datasource that returns JSON. Plugins must be written in Python.
 
 Inventory
 =========
 
-By default, Ansible represents what machines it manages using a very simple INI file that puts all of your managed machines in groups of your own choosing.
+By default, Ansible represents the machines it manages in a file (INI, YAML, etc.) that puts all of your managed machines in groups of your own choosing.
 
 To add new machines, there is no additional SSL signing server involved, so there's never any hassle deciding why a particular machine didn't get linked up due to obscure NTP or DNS issues.
 
-If there's another source of truth in your infrastructure, Ansible can also plugin to that, such as drawing inventory, group, and variable information from sources like EC2, Rackspace, OpenStack, and more.
+If there's another source of truth in your infrastructure, Ansible can also connect to that. Ansible can draw inventory, group, and variable information from sources like EC2, Rackspace, OpenStack, and more.
 
 Here's what a plain text inventory file looks like::
 
@@ -67,8 +76,74 @@ Here's what a simple playbook looks like::
     - common
     - content
 
+.. _ansible_search_path:
 
-Extending Ansible with plug-ins and the API
-===========================================
+The Ansible search path
+=======================
 
-Should you want to write your own, Ansible modules can be written in any language that can return JSON (Ruby, Python, bash, etc). Inventory can also plug in to any datasource by writing a program that speaks to that datasource and returns JSON. There's also various Python APIs for extending Ansible's connection types (SSH is not the only transport possible), callbacks (how Ansible logs, etc), and even for adding new server side behaviors.
+Modules, module utilities, plugins, playbooks, and roles can live in multiple locations. If you
+write your own code to extend Ansible's core features, you may have multiple files with similar or the same names in different locations on your Ansible control node. The search path determines which of these files Ansible will discover and use on any given playbook run.
+
+Ansible's search path grows incrementally over a run. As
+Ansible finds each playbook and role included in a given run, it appends
+any directories related to that playbook or role to the search path. Those
+directories remain in scope for the duration of the run, even after the playbook or role
+has finished executing. Ansible loads modules, module utilities, and plugins in this order:
+
+1. Directories adjacent to a playbook specified on the command line. If you run Ansible with ``ansible-playbook /path/to/play.yml``, Ansible appends these directories if they exist:
+
+   .. code-block:: bash
+
+      /path/to/modules
+      /path/to/module_utils
+      /path/to/plugins
+
+2. Directories adjacent to a playbook that is statically imported by a
+   playbook specified on the command line. If ``play.yml`` includes
+   ``- import_playbook: /path/to/subdir/play1.yml``, Ansible appends these directories if they exist:
+
+   .. code-block:: bash
+
+      /path/to/subdir/modules
+      /path/to/subdir/module_utils
+      /path/to/subdir/plugins
+
+3. Subdirectories of a role directory referenced by a playbook. If
+   ``play.yml`` runs ``myrole``, Ansible appends these directories if they exist:
+
+   .. code-block:: bash
+
+      /path/to/roles/myrole/modules
+      /path/to/roles/myrole/module_utils
+      /path/to/roles/myrole/plugins
+
+4. Directories specified as default paths in ``ansible.cfg`` or by the related
+   environment variables, including the paths for the various plugin types. See :ref:`ansible_configuration_settings` for more information.
+   Sample ``ansible.cfg`` fields:
+
+   .. code-block:: bash
+
+      DEFAULT_MODULE_PATH
+      DEFAULT_MODULE_UTILS_PATH
+      DEFAULT_CACHE_PLUGIN_PATH
+      DEFAULT_FILTER_PLUGIN_PATH
+
+   Sample environment variables:
+
+   .. code-block:: bash
+
+      ANSIBLE_LIBRARY
+      ANSIBLE_MODULE_UTILS
+      ANSIBLE_CACHE_PLUGINS
+      ANSIBLE_FILTER_PLUGINS
+
+5. The standard directories that ship as part of the Ansible distribution.
+
+.. caution::
+
+   Modules, module utilities, and plugins in user-specified directories will
+   override the standard versions. This includes some files with generic names.
+   For example, if you have a file named ``basic.py`` in a user-specified
+   directory, it will override the standard ``ansible.module_utils.basic``.
+
+   If you have more than one module, module utility, or plugin with the same name in different user-specified directories, the order of commands at the command line and the order of includes and roles in each play will affect which one is found and used on that particular play.

docs/docsite/rst/dev_guide/testing_documentation.rst

@@ -10,17 +10,27 @@ Before you submit a module for inclusion in the main Ansible repo, you must test
 
 To check the HTML output of your module documentation:
 
-#. Save your completed module file into the correct directory: ``lib/ansible/modules/$CATEGORY/my_code.py``.
-#. Move to the docsite directory: ``cd /path/to/ansible/docs/docsite/``.
-#. Run the command to build the docs for your module: ``MODULES=my_code make webdocs``.
-#. View the HTML page at ``file:///path/to/ansible/docs/docsite/_build/html/my_code_module.html``.
+#. Ensure working :ref:`development environment <environment_setup>`.
+#. Install required Python packages (drop '--user' in venv/virtualenv):
 
-To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=my_code,my_other_code make webdocs``.
+   .. code-block:: bash
 
-To ensure that your documentation matches your ``argument_spec``, run the ``validate-modules`` test.
+      pip install --user -r requirements.txt
+      pip install --user -r docs/docsite/requirements.txt
 
-.. code-block:: bash
+#. Ensure your module is in the correct directory: ``lib/ansible/modules/$CATEGORY/mymodule.py``.
+#. Build HTML from your module documentation: ``MODULES=mymodule make webdocs``.
+#. To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=mymodule,mymodule2 make webdocs``.
+#. View the HTML page at ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.html``.
 
-   # If you don't already, ensure you are using your local checkout
-   source hacking/env-setup
-   ./test/sanity/validate-modules/validate-modules --arg-spec --warnings  lib/ansible/modules/$CATEGORY/my_code.py
+To ensure that your module documentation matches your ``argument_spec``:
+
+#. Install required Python packages (drop '--user' in venv/virtualenv):
+
+   .. code-block:: bash
+
+      pip install --user -r test/runner/requirements/sanity.txt
+
+#. run the ``validate-modules`` test::
+
+   ./test/sanity/validate-modules/validate-modules --arg-spec --warnings lib/ansible/modules/$CATEGORY/mymodule.py

docs/docsite/rst/dev_guide/testing_units.rst

@@ -43,6 +43,11 @@ Or against a specific Python version by doing:
 
    ansible-test units --tox --python 2.7 apt
 
+If you are running unit tests against things other than modules, such as module utilities, specify the whole file path:
+
+.. code:: shell
+
+   ansible-test units --tox test/units/module_utils/basic/test_imports.py
 
 For advanced usage see the online help::
 

docs/docsite/rst/dev_guide/testing_units_modules.rst

@@ -190,8 +190,9 @@ above, either by throwing an exception or ensuring that they haven't been called
     class AnsibleExitJson(Exception):
         """Exception class to be raised by module.exit_json and caught by the test case"""
         pass
-    #you may also do the same to fail json
-    module=MagicMock()
+
+    # you may also do the same to fail json
+    module = MagicMock()
     module.exit_json.side_effect = AnsibleExitJson(Exception)
     with self.assertRaises(AnsibleExitJson) as result:
         return = my_module.test_this_function(module, argument)
@@ -287,27 +288,22 @@ Passing Arguments
 .. This section should be updated once https://github.com/ansible/ansible/pull/31456 is
    closed since the function below will be provided in a library file.
 
-To pass arguments to a module correctly, use a function that stores the
-parameters in a special string variable.  Module creation and argument processing is
+To pass arguments to a module correctly, use the ``set_module_args`` method which accepts a dictionary
+as its parameter. Module creation and argument processing is
 handled through the :class:`AnsibleModule` object in the basic section of the utilities. Normally
 this accepts input on ``STDIN``, which is not convenient for unit testing. When the special
-variable is set it will be treated as if the input came on ``STDIN`` to the module.::
+variable is set it will be treated as if the input came on ``STDIN`` to the module. Simply call that function before setting up your module::
 
-    import json
-    from ansible.module_utils._text import to_bytes
+    import json 
+    from units.modules.utils import set_module_args 
+    from ansible.module_utils._text import to_bytes 
 
-    def set_module_args(args):
-        args = json.dumps({'ANSIBLE_MODULE_ARGS': args})
-        basic._ANSIBLE_ARGS = to_bytes(args)
-
-    simply call that function before setting up your module
-
-        def test_already_registered(self):
-            set_module_args({
-                'activationkey': 'key',
-                'username': 'user',
-                'password': 'pass',
-            })
+    def test_already_registered(self):
+        set_module_args({
+            'activationkey': 'key',
+            'username': 'user',
+            'password': 'pass',
+        })
 
 Handling exit correctly
 -----------------------
@@ -334,8 +330,9 @@ testing for the correct exception::
             'username': 'user',
             'password': 'pass',
         })
-       with self.assertRaises(AnsibleExitJson) as result:
-           my_module.main()
+
+        with self.assertRaises(AnsibleExitJson) as result:
+            my_module.main()
 
 The same technique can be used to replace :meth:`module.fail_json` (which is used for failure
 returns from modules) and for the ``aws_module.fail_json_aws()`` (used in modules for Amazon
@@ -349,7 +346,7 @@ the arguments as above, set up the appropriate exit exception and then run the m
 
     # This test is based around pytest's features for individual test functions
     import pytest
-    import ansible.modules.module.group.my_modulle as my_module
+    import ansible.modules.module.group.my_module as my_module
 
     def test_main_function(monkeypatch):
         monkeypatch.setattr(my_module.AnsibleModule, "exit_json", fake_exit_json)
@@ -511,7 +508,7 @@ This now makes it possible to run tests against the module initiation function::
          })
 
         with self.assertRaises(AnsibleFailJson) as result:
-             self.module.setup_json
+            self.module.setup_json
 
 See also ``test/units/module_utils/aws/test_rds.py``
 
@@ -559,8 +556,8 @@ the code in Ansible to trigger that failure.
        General advice on testing Python code
    `Uncle Bob's many videos on YouTube <https://www.youtube.com/watch?v=QedpQjxBPMA&list=PLlu0CT-JnSasQzGrGzddSczJQQU7295D2>`_
        Unit testing is a part of the of various philosophies of software development, including
-       Extreme Programming (XP), Clean Coding.  Uncle Bob talks through how to benfit from this
-   `"Why Most Unit Testing is Waste" https://rbcs-us.com/documents/Why-Most-Unit-Testing-is-Waste.pdf`
+       Extreme Programming (XP), Clean Coding.  Uncle Bob talks through how to benefit from this
+   `"Why Most Unit Testing is Waste" <https://rbcs-us.com/documents/Why-Most-Unit-Testing-is-Waste.pdf>`_
        An article warning against the costs of unit testing
-   `'A Response to "Why Most Unit Testing is Waste"' https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/`
+   `'A Response to "Why Most Unit Testing is Waste"' <https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/>`_
        An response pointing to how to maintain the value of unit tests

docs/docsite/rst/installation_guide/intro_installation.rst

@@ -150,7 +150,7 @@ To configure the PPA on your machine and install ansible run these commands:
     $ sudo apt-add-repository --yes --update ppa:ansible/ansible
     $ sudo apt install ansible
 
-.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` instead of ``apt`` in older versions.
+.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` instead of ``apt`` in older versions. Also, be aware that only newer distributions (i.e. 18.04, 18.10, etc.) have a ``-u`` or ``--update`` flag, so adjust your script accordingly.
 
 Debian/Ubuntu packages can also be built from the source checkout, run:
 

docs/docsite/rst/network/dev_guide/developing_plugins_network.rst

@@ -0,0 +1,118 @@
+
+.. _developing_modules_network:
+.. _developing_plugins_network:
+
+**************************
+Network connection plugins
+**************************
+
+Each network connection plugin has a set of its own plugins which provide a specification of the
+connection for a particular set of devices. The specific plugin used is selected at runtime based
+on the value of the ``ansible_network_os`` variable assigned to the host. This variable should be
+set to the same value as the name of the plugin to be loaed. Thus, ``ansible_network_os=nxos``
+will try to load a plugin in a file named ``nxos.py``, so it is important to name the plugin in a
+way that will be sensible to users.
+
+Public methods of these plugins may be called from a module or module_utils with the connection
+proxy object just as other connection methods can. The following is a very simple example of using
+such a call in a module_utils file so it may be shared with other modules.
+
+.. code-block:: python
+
+  from ansible.module_utils.connection import Connection
+
+  def get_config(module):
+      # module is your AnsibleModule instance.
+      connection = Connection(module._socket_path)
+
+      # You can now call any method (that doesn't start with '_') of the connection
+      # plugin or its platform-specific plugin
+      return connection.get_config()
+
+.. contents::
+   :local:
+
+.. _developing_plugins_httpapi:
+
+Developing httpapi plugins
+==========================
+
+:ref:`httpapi plugins <httpapi_plugins>` serve as adapters for various HTTP(S) APIs for use with the ``httpapi`` connection plugin. They should implement a minimal set of convenience methods tailored to the API you are attempting to use.
+
+Specifically, there are a few methods that the ``httpapi`` connection plugin expects to exist.
+
+Making requests
+---------------
+
+The ``httpapi`` connection plugin has a ``send()`` method, but an httpapi plugin needs a ``send_request(self, data, **message_kwargs)`` method as a higher-level wrapper to ``send()``. This method should prepare requests by adding fixed values like common headers or URL root paths. This method may do more complex work such as turning data into formatted payloads, or determining which path or method to request. It may then also unpack responses to be more easily consumed by the caller.
+
+.. code-block:: python
+
+   from ansible.module_utils.six.moves.urllib.error import HTTPError
+
+   def send_request(self, data, path, method='POST'):
+       # Fixed headers for requests
+       headers = {'Content-Type': 'application/json'}
+       try:
+           response, response_content = self.connection.send(path, data, method=method, headers=headers)
+       except HTTPError as exc:
+           return exc.code, exc.read()
+
+       # handle_response (defined separately) will take the format returned by the device
+       # and transform it into something more suitable for use by modules.
+       # This may be JSON text to Python dictionaries, for example.
+       return handle_response(response_content)
+
+Authenticating
+--------------
+
+By default, all requests will authenticate with HTTP Basic authentication. If a request can return some kind of token to stand in place of HTTP Basic, the ``update_auth(self, response, response_text)`` method should be implemented to inspect responses for such tokens. If the token is meant to be included with the headers of each request, it is sufficient to return a dictionary which will be merged with the computed headers for each request. The default implementation of this method does exactly this for cookies. If the token is used in another way, say in a query string, you should instead save that token to an instance variable, where the ``send_request()`` method (above) can add it to each request
+
+.. code-block:: python
+
+   def update_auth(self, response, response_text):
+       cookie = response.info().get('Set-Cookie')
+       if cookie:
+           return {'Cookie': cookie}
+
+       return None
+
+If instead an explicit login endpoint needs to be requested to receive an authentication token, the ``login(self, username, password)`` method can be implemented to call that endpoint. If implemented, this method will be called once before requesting any other resources of the server. By default, it will also be attempted once when a HTTP 401 is returned from a request.
+
+.. code-block:: python
+
+   def login(self, username, password):
+       login_path = '/my/login/path'
+       data = {'user': username, 'password': password}
+
+       response = self.send_request(data, path=login_path)
+       try:
+           # This is still sent as an HTTP header, so we can set our connection's _auth
+           # variable manually. If the token is returned to the device in another way,
+           # you will have to keep track of it another way and make sure that it is sent
+           # with the rest of the request from send_request()
+           self.connection._auth = {'X-api-token': response['token']}
+       except KeyError:
+           raise AnsibleAuthenticationFailure(message="Failed to acquire login token.")
+
+Similarly, ``logout(self)`` can be implemented to call an endpoint to invalidate and/or release the current token, if such an endpoint exists. This will be automatically called when the connection is closed (and, by extension, when reset).
+
+.. code-block:: python
+
+   def logout(self):
+       logout_path = '/my/logout/path'
+       self.send_request(None, path=logout_path)
+
+       # Clean up tokens
+       self.connection._auth = None
+
+Error handling
+--------------
+
+The ``handle_httperror(self, exception)`` method can deal with status codes returned by the server. The return value indicates how the plugin will continue with the request:
+
+* A value of ``true`` means that the request can be retried. This my be used to indicate a transient error, or one that has been resolved. For example, the default implementation will try to call ``login()`` when presented with a 401, and return ``true`` if successful.
+
+* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be returned to the calling module as an exception. Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response.
+
+For example httpapi plugins, see the `source code for the httpapi plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/httpapi>`_ included with Ansible Core.

docs/docsite/rst/network/dev_guide/index.rst

@@ -0,0 +1,26 @@
+.. _network_developer_guide:
+
+**************************************
+Developer Guide for Network Automation
+**************************************
+
+Welcome to the Developer Guide for Ansible Network Automation!
+
+**Who should use this guide?**
+
+If you want to extend Ansible for Network Automation by creating a module or plugin, this guide is for you. This guide is specific to networking. You should already be familiar with how to create, test, and document modules and plugins, as well as the prerequisites for getting your module or plugin accepted into the main Ansible repository.  See the  :ref:`developer_guide` for details. Before you proceed, please read:
+
+* How  to :ref:`add a custom plugin or module locally <developing_locally>`.
+* How to figure out if :ref:`developing a module is the right approach <module_dev_should_you>` for my use case.
+* How to :ref:`set up my Python development environment <environment_setup>`.
+* How to :ref:`get started writing a module <developing_modules_general>`.
+
+
+Find the network developer task that best describes what you want to do:
+
+   * I want to :ref:`develop a network connection plugin <developing_plugins_network>`.
+
+.. toctree::
+  :maxdepth: 1
+
+  developing_plugins_network

docs/docsite/rst/network/index.rst

@@ -15,3 +15,4 @@ For documentation on using a particular network module, consult the :ref:`list o
 
    getting_started/index
    user_guide/index
+   dev_guide/index

docs/docsite/rst/plugins/httpapi.rst

@@ -18,7 +18,7 @@ others might be usable on a variety of platforms (RESTCONF).
 Adding httpapi plugins
 -------------------------
 
-You can extend Ansible to support other APIs by dropping a custom plugin into the ``httpapi_plugins`` directory.
+You can extend Ansible to support other APIs by dropping a custom plugin into the ``httpapi_plugins`` directory. See :ref:`developing_plugins_httpapi` for details.
 
 .. _using_httpapi:
 
@@ -51,6 +51,8 @@ Use ``ansible-doc -t httpapi <plugin name>`` to see detailed documentation and e
 
    :ref:`Ansible for Network Automation<network_guide>`
        An overview of using Ansible to automate networking devices.
+   :ref:`Developing network modules<developing_modules_network>`
+       How to develop network modules.
    `User Mailing List <https://groups.google.com/group/ansible-devel>`_
        Have a question?  Stop by the google group!
    `irc.freenode.net <http://irc.freenode.net>`_

docs/docsite/rst/plugins/inventory.rst

@@ -55,7 +55,7 @@ Or for the openstack plugin the file has to be called ``clouds.yml`` or ``openst
     # clouds.yml or openstack.(yml|yaml)
     plugin: openstack
 
-The ``auto`` inventory plugin is enabled by default and works by using the ``plugin`` field to indicate the plugin that should attempt to parse it. You can configure the whitelist/precedence of inventory plugins used to parse source using the `ansible.cfg` ['inventory'] ``enable_plugins`` list. After enabling the plugin and providing any required options you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``:
+The ``auto`` inventory plugin is enabled by default and works by using the ``plugin`` field to indicate the plugin that should attempt to parse it. You can configure the whitelist/precedence of inventory plugins used to parse source using the `ansible.cfg` ['inventory'] ``enable_plugins`` list. After enabling the plugin and providing any required options, you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``:
 
 .. code-block:: text
 

docs/docsite/rst/porting_guides/porting_guide_2.5.rst

@@ -143,7 +143,7 @@ Ansible fact namespacing
 Ansible facts, which have historically been written to names like ``ansible_*``
 in the main facts namespace, have been placed in their own new namespace,
 ``ansible_facts.*`` For example, the fact ``ansible_distribution`` is now best
-queried through the variable structure ``ansible_facts.distribution``. 
+queried through the variable structure ``ansible_facts.distribution``.
 
 A new configuration variable, ``inject_facts_as_vars``, has been added to
 ansible.cfg. Its default setting, 'True', keeps the 2.4 behavior of facts
@@ -389,4 +389,4 @@ If your module uses shared module utilities, you must update all references. For
    from ansible.module_utils.network.vyos.vyos import get_config, load_config
 
 
-See the module utilities developer guide see :ref:`appendix_module_utilities` for more information.
+See the module utilities developer guide see :ref:`developing_module_utilities` for more information.

docs/docsite/rst/porting_guides/porting_guide_2.8.rst

@@ -8,7 +8,7 @@ This section discusses the behavioral changes between Ansible 2.7 and Ansible 2.
 
 It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.
 
-We suggest you read this page along with `Ansible Changelog for 2.8 <https://github.com/ansible/ansible/blob/devel/changelogs/CHANGELOG-v2.8.rst>`_ to understand what updates you may need to make.
+We suggest you read this page along with `Ansible Changelog for 2.8 <https://github.com/ansible/ansible/blob/stable-2.8/changelogs/CHANGELOG-v2.8.rst>`_ to understand what updates you may need to make.
 
 This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
 
@@ -35,7 +35,7 @@ Beginning in version 2.8, a task cannot notify ``import_tasks`` or a static ``in
 The goal of a static import is to act as a pre-processor, where the import is replaced by the tasks defined within the imported file. When
 using an import, a task can notify any of the named tasks within the imported file, but not the name of the import itself.
 
-To achieve the results of notifying a single name but running mulitple handlers, utilize ``include_tasks``, or ``listen`` :ref:`handlers`.
+To achieve the results of notifying a single name but running multiple handlers, utilize ``include_tasks``, or ``listen`` :ref:`handlers`.
 
 Jinja Undefined values
 ----------------------
@@ -153,7 +153,7 @@ Command Line
 Become Prompting
 ----------------
 
-Beginning in version 2.8, by default Ansible will use the word ``BECOME`` to prompt you for a password for elevated privileges (``sudo`` privileges on unix systems or ``enable`` mode on network devices):
+Beginning in version 2.8, by default Ansible will use the word ``BECOME`` to prompt you for a password for elevated privileges (``sudo`` privileges on Unix systems or ``enable`` mode on network devices):
 
 By default in Ansible 2.8::
 
@@ -190,7 +190,7 @@ Deprecated
   2. The ``FactCache.update()`` method has been converted to follow the dict API.  It now takes a
      dictionary as its sole argument and updates itself with the dictionary's items.  The previous
      API where ``update()`` took a key and a value will now issue a deprecation warning and will be
-     removed in 2.12.  If you need the old behaviour switch to ``FactCache.first_order_merge()``
+     removed in 2.12.  If you need the old behavior switch to ``FactCache.first_order_merge()``
      instead.
 
 * Supporting file-backed caching via self.cache is deprecated and will
@@ -212,9 +212,9 @@ Modules
 Major changes in popular modules are detailed here
 
 The exec wrapper that runs PowerShell modules has been changed to set ``$ErrorActionPreference = "Stop"`` globally.
-This may mean that custom modules can fail if they implicitly relied on this behaviour. To get the old behaviour back,
-add ``$ErrorActionPreference = "Continue"`` to the top of the module. This change was made to restore the old behaviour
-of the EAP that was accidentally removed in a previous release and ensure that modules are more resiliant to errors
+This may mean that custom modules can fail if they implicitly relied on this behavior. To get the old behavior back,
+add ``$ErrorActionPreference = "Continue"`` to the top of the module. This change was made to restore the old behavior
+of the EAP that was accidentally removed in a previous release and ensure that modules are more resilient to errors
 that may occur in execution.
 
 Modules removed
@@ -238,6 +238,14 @@ The following modules will be removed in Ansible 2.12. Please update your playbo
 * ``github_hooks`` use :ref:`github_webhook <github_webhook_module>` and :ref:`github_webhook_facts <github_webhook_facts_module>` instead.
 * ``digital_ocean`` use :ref:`digital_ocean_droplet <digital_ocean_droplet_module>` instead.
 * ``gce`` use :ref:`gcp_compute_instance <gcp_compute_instance_module>` instead.
+* ``gcspanner`` use :ref:`gcp_spanner_instance <gcp_spanner_instance_module>` and :ref:`gcp_spanner_database <gcp_spanner_database_module>` instead.
+* ``gcdns_record`` use :ref:`gcp_dns_resource_record_set <gcp_dns_resource_record_set_module>` instead.
+* ``gcdns_zone`` use :ref:`gcp_dns_managed_zone <gcp_dns_managed_zone_module>` instead.
+* ``gcp_forwarding_rule`` use :ref:`gcp_compute_global_forwarding_rule <gcp_compute_global_forwarding_rule_module>` or :ref:`gcp_compute_forwarding_rule <gcp_compute_forwarding_rule_module>` instead.
+* ``gcp_healthcheck`` use :ref:`gcp_compute_health_check <gcp_compute_health_check_module>`, :ref:`gcp_compute_http_health_check <gcp_compute_http_health_check_module>`, or :ref:`gcp_compute_https_health_check <gcp_compute_https_health_check_module>` instead.
+* ``gcp_backend_service`` use :ref:`gcp_compute_backend_service <gcp_compute_backend_service_module>` instead.
+* ``gcp_target_proxy`` use :ref:`gcp_compute_target_http_proxy <gcp_compute_target_http_proxy_module>` instead.
+* ``gcp_url_map`` use :ref:`gcp_compute_url_map <gcp_compute_url_map_module>` instead.
 * ``panos`` use the `Palo Alto Networks Ansible Galaxy role <https://galaxy.ansible.com/PaloAltoNetworks/paloaltonetworks>`_ instead.
 
 
@@ -252,16 +260,16 @@ Noteworthy module changes
 * The ``win_scheduled_task`` module deprecated support for specifying a trigger repetition as a list and this format
   will be removed in Ansible 2.12. Instead specify the repetition as a dictionary value.
 
-* The ``win_feature`` module has removed the deprecated ``restart_needed`` return value, use the standardised
+* The ``win_feature`` module has removed the deprecated ``restart_needed`` return value, use the standardized
   ``reboot_required`` value instead.
 
 * The ``win_package`` module has removed the deprecated ``restart_required`` and ``exit_code`` return value, use the
-  standardised ``reboot_required`` and ``rc`` value instead.
+  standardized ``reboot_required`` and ``rc`` value instead.
 
 * The ``win_get_url`` module has removed the deprecated ``win_get_url`` return dictionary, contained values are
   returned directly.
 
-* The ``win_get_url`` module has removed the deprecated ``skip_certificate_validation`` option, use the standardised
+* The ``win_get_url`` module has removed the deprecated ``skip_certificate_validation`` option, use the standardized
   ``validate_certs`` option instead.
 
 * The ``vmware_local_role_facts`` module now returns a list of dicts instead of a dict of dicts for role information.
@@ -409,5 +417,5 @@ Networking
   ``save`` and ``force`` parameters, use the ``save_when`` parameter to replicate their
   functionality.
 
-* The ``nxos_vrf_af`` module has removed the ``safi`` paramter. This parameter was deprecated
+* The ``nxos_vrf_af`` module has removed the ``safi`` parameter. This parameter was deprecated
   in Ansible 2.4 and has had no impact on the module since then.

docs/docsite/rst/porting_guides/porting_guides.rst

@@ -10,11 +10,7 @@ Please note that this is not a complete list. If you believe any extra informati
 
 .. toctree::
    :maxdepth: 2
-  
-   porting_guide_2.0
-   porting_guide_2.3
-   porting_guide_2.4
-   porting_guide_2.5
-   porting_guide_2.6
-   porting_guide_2.7
-   porting_guide_2.8
+   :glob:
+   :reversed:
+
+   porting_guide_*

docs/docsite/rst/reference_appendices/faq.rst

@@ -96,6 +96,13 @@ With earlier versions of Ansible, it was necessary to configure a
 suitable `ProxyCommand` for one or more hosts in `~/.ssh/config`,
 or globally by setting `ssh_args` in `ansible.cfg`.
 
+.. _ssh_serveraliveinterval:
+
+How do I get Ansible to notice a dead target in a timely manner?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+You can add ``-o ServerAliveInterval=NumberOfSeconds`` in ``ssh_args`` from ``ansible.cfg``. Without this option, SSH and therefore Ansible will wait until the TCP connection times out. Another solution is to add ``ServerAliveInterval`` into your global SSH configuration. A good value for ``ServerAliveInterval`` is up to you to decide; keep in mind that ``ServerAliveCountMax=3`` is the SSH default so any value you set will be tripled before terminating the SSH session.
+
 .. _ec2_cloud_performance:
 
 How do I speed up management inside EC2?
@@ -231,11 +238,11 @@ There are a few common errors that one might run into when trying to execute Ans
 
   To get around this limitation, download and install a later version of `python for z/OS <https://www.rocketsoftware.com/zos-open-source>`_ (2.7.13 or 3.6.1) that represents strings internally as ASCII.  Version 2.7.13 is verified to work.
 
-* When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with 
+* When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with
 
   .. error::
       SyntaxError: Non-UTF-8 code starting with \'\\x83\' in file /a/user1/.ansible/tmp/ansible-tmp-1548232945.35-274513842609025/AnsiballZ_stat.py on line 1, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details
-  
+
   To fix it set ``pipelining = True`` in `/etc/ansible/ansible.cfg`.
 
 * Python interpret cannot be found in default location ``/usr/bin/python`` on target host.
@@ -643,6 +650,32 @@ but you can still access the original via ``hostvars``::
 This works for all overriden connection variables, like ``ansible_user``, ``ansible_port``, etc.
 
 
+.. _scp_protocol_error_filename:
+
+How do I fix 'protocol error: filename does not match request' when fetching a file?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Newer releases of OpenSSH have a `bug <https://bugzilla.mindrot.org/show_bug.cgi?id=2966>`_ in the SCP client that can trigger this error on the Ansible controller when using SCP as the file transfer mechanism::
+
+    failed to transfer file to /tmp/ansible/file.txt\r\nprotocol error: filename does not match request
+
+In these releases, SCP tries to validate that the path of the file to fetch matches the requested path.
+The validation
+fails if the remote filename requires quotes to escape spaces or non-ascii characters in its path. To avoid this error:
+
+* Use SFTP instead of SCP by setting ``scp_if_ssh`` to ``smart`` (which tries SFTP first) or to ``False``. You can do this in one of four ways:
+    * Rely on the default setting, which is ``smart`` - this works if ``scp_if_ssh`` is not explicitly set anywhere
+    * Set a :ref:`host variable <host_variables>` or :ref:`group variable <group_variables>` in inventory: ``ansible_scp_if_ssh: False``
+    * Set an environment variable on your control node: ``export ANSIBLE_SCP_IF_SSH=False``
+    * Pass an environment variable when you run Ansible: ``ANSIBLE_SCP_IF_SSH=smart ansible-playbook``
+    * Modify your ``ansible.cfg`` file: add ``scp_if_ssh=False`` to the ``[ssh_connection]`` section
+* If you must use SCP, set the ``-T`` arg to tell the SCP client to ignore path validation. You can do this in one of three ways:
+    * Set a :ref:`host variable <host_variables>` or :ref:`group variable <group_variables>`: ``ansible_scp_extra_args=-T``,
+    * Export or pass an environment variable: ``ANSIBLE_SCP_EXTRA_ARGS=-T``
+    * Modify your ``ansible.cfg`` file: add ``scp_extra_args=-T`` to the ``[ssh_connection]`` section
+
+.. note:: If you see an ``invalid argument`` error when using ``-T``, then your SCP client is not performing filename validation and will not trigger this error.
+
 .. _i_dont_see_my_question:
 
 I don't see my question here

docs/docsite/rst/reference_appendices/galaxy.rst

@@ -43,12 +43,11 @@ Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <h
 roles_path
 ==========
 
-Be aware that by default Ansible downloads roles to the path specified by the environment variable :envvar:`ANSIBLE_ROLES_PATH`. This can be set to a series of
-directories (i.e. */etc/ansible/roles:~/.ansible/roles*), in which case the first writable path will be used. When Ansible is first installed it defaults
-to */etc/ansible/roles*, which requires *root* privileges.
+By default Ansible downloads roles to the first writable directory in the default list of paths ``~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles``. This will install roles in the home directory of the user running ``ansible-galaxy``.
 
-You can override this by setting the environment variable in your session, defining *roles_path* in an *ansible.cfg* file, or by using the *--roles-path* option.
-The following provides an example of using *--roles-path* to install the role into the current working directory:
+You can override this by setting the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session, defining ``roles_path`` in an ``ansible.cfg`` file, or by using the ``--roles-path`` option.
+
+The following provides an example of using ``--roles-path`` to install the role into the current working directory:
 
 ::
 

docs/docsite/rst/reference_appendices/release_and_maintenance.rst

@@ -38,10 +38,11 @@ This table links to the release notes for each major release. These release note
 ==============================      =================================================
 Ansible Release                     Status
 ==============================      =================================================
-devel                               In development (2.8 unreleased, trunk)
-`2.7 Release Notes`_                Supported (security **and** general bug fixes)
-`2.6 Release Notes`_                Supported (security **and** critical bug fixes)
-`2.5 Release Notes`_                Supported (security fixes)
+devel                               In development (2.9 unreleased, trunk)
+`2.8 Release Notes`_                Supported (security **and** general bug fixes)
+`2.7 Release Notes`_                Supported (security **and** critical bug fixes)
+`2.6 Release Notes`_                Supported (security fixes)
+`2.5 Release Notes`_                Unsupported (end of life)
 `2.4 Release Notes`_                Unsupported (end of life)
 `2.3 Release Notes`_                Unsupported (end of life)
 `2.2 Release Notes`_                Unsupported (end of life)
@@ -53,12 +54,14 @@ devel                               In development (2.8 unreleased, trunk)
 
 You can download the releases from `<https://releases.ansible.com/ansible/>`_.
 
-.. note:: Starting with Ansible-2.4, support lasts for 3 releases.  Thus Ansible-2.4 will receive
+.. note:: Ansible support lasts for 3 releases.  Thus the latest Ansible release receives
     security and general bug fixes when it is first released, security and critical bug fixes when
-    2.5 is released, and **only** security fixes once 2.6 is released.
+    the next Ansible version is released, and **only** security fixes once the follow on to that version is released.
 
 .. Comment: devel used to point here but we're currently revamping our changelog process and have no
    link to a static changelog for devel _2.6: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
+.. _2.8 Release Notes:
+.. _2.8: https://github.com/ansible/ansible/blob/stable-2.8/changelogs/CHANGELOG-v2.8.rst
 .. _2.7 Release Notes: https://github.com/ansible/ansible/blob/stable-2.7/changelogs/CHANGELOG-v2.7.rst
 .. _2.6 Release Notes:
 .. _2.6: https://github.com/ansible/ansible/blob/stable-2.6/changelogs/CHANGELOG-v2.6.rst
@@ -89,10 +92,6 @@ major release will only receive fixes for security issues and critical bugs. Ans
 security fixes to releases which are two releases old. This work is tracked on the
 ``stable-<version>`` git branches.
 
-.. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions
-    are only supported for two releases with the first stage including both security and general bug
-    fixes while the second stage includes security and critical bug fixes
-
 The fixes that land in supported stable branches will eventually be released
 as a new version when necessary.
 
@@ -108,7 +107,7 @@ Changelogs
 
 Older versions logged changes in ``stable-<version>`` branches at ``stable-<version>/CHANGELOG.md``. For example, here is the changelog for 2.4_ on GitHub.
 
-We now generate changelogs based on fragments. Here is the generated changelog for 2.6_ as an example. When creating new features or fixing bugs, create a changelog fragment describing the change. A changelog entry is not needed for new modules or plugins. Details for those items will be generated from the module documentation.
+We now generate changelogs based on fragments. Here is the generated changelog for 2.8_ as an example. When creating new features or fixing bugs, create a changelog fragment describing the change. A changelog entry is not needed for new modules or plugins. Details for those items will be generated from the module documentation.
 
 We've got :ref:`examples and instructions on creating changelog fragments <changelogs_how_to>` in the Community Guide.
 

docs/docsite/rst/roadmap/ROADMAP_2_8.rst

@@ -21,8 +21,8 @@ PRs must be raised well in advance of the dates below to have a chance of being
   No new functionality (including modules/plugins) to any code
 
 - 2019-04-25 Release Candidate 1
-- 2019-05-02 Release Candidate 2 (if needed)
-- 2019-05-09 Release Candidate 3 (if needed)
+- 2019-05-02 Release Candidate 2
+- 2019-05-10 Release Candidate 3
 - 2019-05-16 Release
 
 

docs/docsite/rst/scenario_guides/guide_aws.rst

@@ -18,7 +18,6 @@ Whereas classically ansible will execute tasks in its host loop against multiple
 In your playbook steps we'll typically be using the following pattern for provisioning steps::
 
     - hosts: localhost
-      connection: local
       gather_facts: False
       tasks:
         - ...
@@ -68,7 +67,6 @@ instance.::
     # demo_setup.yml
 
     - hosts: localhost
-      connection: local
       gather_facts: False
 
       tasks:
@@ -94,7 +92,6 @@ From this, we'll use the add_host module to dynamically create a host group cons
     # demo_setup.yml
 
     - hosts: localhost
-      connection: local
       gather_facts: False
 
       tasks:
@@ -135,6 +132,37 @@ With the host group now created, a second play at the bottom of the same provisi
          - name: Check NTP service
            service: name=ntpd state=started
 
+.. _aws_security_groups:
+
+Security Groups
+```````````````
+
+Security groups on AWS are stateful. The response of a request from your instance is allowed to flow in regardless of inbound security group rules and vice-versa.
+In case you only want allow traffic with AWS S3 service, you need to fetch the current IP ranges of AWS S3 for one region and apply them as an egress rule.::
+
+    - name: fetch raw ip ranges for aws s3
+      set_fact:
+        raw_s3_ranges: "{{ lookup('aws_service_ip_ranges', region='eu-central-1', service='S3', wantlist=True) }}"
+
+    - name: prepare list structure for ec2_group module
+      set_fact:
+        s3_ranges: "{{ s3_ranges | default([]) + [{'proto': 'all', 'cidr_ip': item, 'rule_desc': 'S3 Service IP range'}] }}"
+      with_items: "{{ raw_s3_ranges }}"
+
+    - name: set S3 IP ranges to egress rules
+      ec2_group:
+        name: aws_s3_ip_ranges
+        description: allow outgoing traffic to aws S3 service
+        region: eu-central-1
+        state: present
+        vpc_id: vpc-123456
+        purge_rules: true
+        purge_rules_egress: true
+        rules: []
+        rules_egress: "{{ s3_ranges }}"
+        tags:
+          Name: aws_s3_ip_ranges
+
 .. _aws_host_inventory:
 
 Host Inventory

docs/docsite/rst/scenario_guides/guide_gce.rst

@@ -29,7 +29,7 @@ used, but you may experience issues trying to use them together.
 
 While the community GCP modules are not going away, Google is investing effort
 into the new "gcp_*" modules. Google is committed to ensuring the Ansible
-community has a great experience with GCP and therefore recommends adopting 
+community has a great experience with GCP and therefore recommends adopting
 these new modules if possible.
 
 
@@ -42,7 +42,7 @@ The Google Cloud Platform (GCP) modules require both the ``requests`` and the
 
     $ pip install requests google-auth
 
-Alternatively for RHEL / CentOS, the ``python-requests`` package is also 
+Alternatively for RHEL / CentOS, the ``python-requests`` package is also
 available to satisfy ``requests`` libraries.
 
 .. code-block:: bash
@@ -81,14 +81,13 @@ For the GCE modules you can specify the credentials as arguments:
 * ``project``: id of the project
 * ``scopes``: The specific scopes that you want the actions to use.
 
-For example, to create a new IP address using the `gcp_compute_address` module,
+For example, to create a new IP address using the ``gcp_compute_address`` module,
 you can use the following configuration:
 
 .. code-block:: yaml
 
    - name: Create IP address
      hosts: localhost
-     connection: local
      gather_facts: no
 
      vars:
@@ -96,7 +95,7 @@ you can use the following configuration:
        project: my-project
        auth_kind: serviceaccount
        scopes:
-         - www.googleapis.com/auth/compute
+         - https://www.googleapis.com/auth/compute
 
      tasks:
 
@@ -169,11 +168,10 @@ rest.
    - name: Create an instance
      hosts: localhost
      gather_facts: no
-     connection: local
      vars:
-         project: my-project
-         auth_kind: serviceaccount
-         service_account_file: /home/my_account.json
+         gcp_project: my-project
+         gcp_cred_kind: serviceaccount
+         gcp_cred_file: /home/my_account.json
          zone: "us-central1-a"
          region: "us-central1"
 
@@ -236,10 +234,10 @@ rest.
         register: instance
 
        - name: Wait for SSH to come up
-         wait_for: host={{ instance.address }} port=22 delay=10 timeout=60
+         wait_for: host={{ address.address }} port=22 delay=10 timeout=60
 
        - name: Add host to groupname
-         add_host: hostname={{ instance.address }} groupname=new_instances
+         add_host: hostname={{ address.address }} groupname=new_instances
 
 
    - name: Manage new instances
@@ -254,3 +252,60 @@ Note that use of the "add_host" module above creates a temporary, in-memory grou
 in the 'new_instances' group, if so desired.  Any sort of arbitrary configuration is possible at this point.
 
 For more information about Google Cloud, please visit the `Google Cloud website <https://cloud.google.com>`_.
+
+Migration Guides
+----------------
+
+gce.py -> gcp_compute_instance.py
+`````````````````````````````````
+As of Ansible 2.8, we're encouraging everyone to move from the ``gce`` module to the
+``gcp_compute_instance`` module. The ``gcp_compute_instance`` module has better
+support for all of GCP's features, fewer dependencies, more flexibility, and
+better supports GCP's authentication systems.
+
+The ``gcp_compute_instance`` module supports all of the features of the ``gce``
+module (and more!). Below is a mapping of ``gce`` fields over to
+``gcp_compute_instance`` fields.
+
+============================  ==========================================  ======================
+ gce.py                        gcp_compute_instance.py                     Notes
+============================  ==========================================  ======================
+ state                        state/status                                State on gce has multiple values: "present", "absent", "stopped", "started", "terminated". State on gcp_compute_instance is used to describe if the instance exists (present) or does not (absent). Status is used to describe if the instance is "started", "stopped" or "terminated".
+ image                        disks[].initialize_params.source_image      You'll need to create a single disk using the disks[] parameter and set it to be the boot disk (disks[].boot = true)
+ image_family                 disks[].initialize_params.source_image      See above.
+ external_projects            disks[].initialize_params.source_image      The name of the source_image will include the name of the project.
+ instance_names               Use a loop or multiple tasks.               Using loops is a more Ansible-centric way of creating multiple instances and gives you the most flexibility.
+ service_account_email        service_accounts[].email                    This is the service_account email address that you want the instance to be associated with. It is not the service_account email address that is used for the credentials necessary to create the instance.
+ service_account_permissions  service_accounts[].scopes                   These are the permissions you want to grant to the instance.
+ pem_file                     Not supported.                              We recommend using JSON service account credentials instead of PEM files.
+ credentials_file             service_account_file
+ project_id                   project
+ name                         name                                        This field does not accept an array of names. Use a loop to create multiple instances.
+ num_instances                Use a loop                                  For maximum flexibility, we're encouraging users to use Ansible features to create multiple instances, rather than letting the module do it for you.
+ network                      network_interfaces[].network
+ subnetwork                   network_interfaces[].subnetwork
+ persistent_boot_disk         disks[].type = 'PERSISTENT'
+ disks                        disks[]
+ ip_forward                   can_ip_forward
+ external_ip                  network_interfaces[].access_configs.nat_ip  This field takes multiple types of values. You can create an IP address with ``gcp_compute_address`` and place the name/output of the address here. You can also place the string value of the IP address's GCP name or the actual IP address.
+ disks_auto_delete            disks[].auto_delete
+ preemptible                  scheduling.preemptible
+ disk_size                    disks[].initialize_params.disk_size_gb
+============================  ==========================================  ======================
+
+An example playbook is below:
+
+.. code:: yaml
+
+  gcp_compute_instance:
+      name: "{{ item }}"
+      machine_type: n1-standard-1
+      ... # any other settings
+      zone: us-central1-a
+      project: "my-project"
+      auth_kind: "service_account_file"
+      service_account_file: "~/my_account.json"
+      state: present
+  with_items:
+    - instance-1
+    - instance-2