WIP: Backport/2.10/71588

docs/docsite/rst/community/committer_guidelines.rst

@@ -15,7 +15,7 @@ If you abuse the trust and break components and builds, and so on, the trust lev
 Features, high-level design, and roadmap
 ========================================
 
-As a core team member, you are an integral part of the team that develops the :ref:`roadmap <roadmaps>`. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, and so on. for various releases. Red Hat, the company, and the Ansible team must get these committed features (and so on.) completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it impacts a lot of other parts within Ansible.
+As a core team member, you are an integral part of the team that develops the :ref:`roadmap <roadmaps>`. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, and so on, for various releases. Red Hat, the company, and the Ansible team must get these changes completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it affects a lot of other parts within Ansible.
 
 Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals.
 
@@ -49,19 +49,19 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe
   - Commit directly.
   - Merge your own PRs. Someone else should have a chance to review and approve the PR merge. If you are a Core Committer, you have a small amount of leeway here for very minor changes.
   - Forget about alternate environments. Consider the alternatives--yes, people have bad environments, but they are the ones who need us the most.
-  - Drag your community team members down. Always discuss the technical merits, but you should never address the person's limitations (you can later go for beers and call them idiots, but not in IRC/GitHub/and so on.).
+  - Drag your community team members down. Always discuss the technical merits, but you should never address the person's limitations (you can later go for beers and call them idiots, but not in IRC/GitHub/and so on).
   - Forget about the maintenance burden. Some things are really cool to have, but they might not be worth shoehorning in if the maintenance burden is too great.
   - Break playbooks. Always keep backwards compatibility in mind.
   - Forget to keep it simple. Complexity breeds all kinds of problems.
 
 * Do
 
   - Squash, avoid merges whenever possible, use GitHub's squash commits or cherry pick if needed (bisect thanks you).
-  - Be active. Committers who have no activity on the project (through merges, triage, commits, and so on.) will have their permissions suspended.
+  - Be active. Committers who have no activity on the project (through merges, triage, commits, and so on) will have their permissions suspended.
   - Consider backwards compatibility (goes back to "don't break existing playbooks").
   - Write tests. PRs with tests are looked at with more priority than PRs without tests that should have them included. While not all changes require tests, be sure to add them for bug fixes or functionality changes.
   - Discuss with other committers, specially when you are unsure of something.
-  - Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of Core against which this documentation is compatible (to avoid confusion with stable versus devel docs, for backwards compatibility, and so on.).
+  - Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of ``ansible-base`` against which this documentation is compatible (to avoid confusion between stable and devel docs, for backwards compatibility, and so on).
   - Consider scope, sometimes a fix can be generalized
   - Keep it simple, then things are maintainable, debuggable and intelligible.
 

docs/docsite/rst/community/documentation_contributions.rst

@@ -53,7 +53,7 @@ A great documentation GitHub issue or PR includes:
 
 - a specific title
 - a detailed description of the problem (even for a PR - it's hard to evaluate a suggested change unless we know what problem it's meant to solve)
-- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on.)
+- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on)
 
 
 Verifying your documentation PR

docs/docsite/rst/community/index.rst

@@ -37,7 +37,7 @@ Going deeper
 * I need functionality that Ansible does not offer. How do I :ref:`request a feature <request_features>`?
 * How do I :ref:`contribute to an Ansible-maintained collection <contributing_maintained_collections>`?
 * I am waiting for a particular feature. How do I see what is :ref:`planned for future Ansible Releases <roadmaps>`?
-* I have a specific Ansible interest or expertise (for example, VMware, Linode, and so on.). How do I get involved in a :ref:`working group <working_group_list>`?
+* I have a specific Ansible interest or expertise (for example, VMware, Linode, and so on). How do I get involved in a :ref:`working group <working_group_list>`?
 * I would like to participate in conversations about features and fixes. How do I review GitHub issues and pull requests?
 * I found a typo or another problem on docs.ansible.com. How can I :ref:`improve the documentation <community_documentation_contributions>`?
 

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -80,7 +80,7 @@ The ``ansible-doc`` command requires the fully qualified collection name (FQCN)
 plugins directory
 ------------------
 
-Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
+Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play.
 
 Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
 
@@ -565,7 +565,7 @@ Create a PR against the old collection repo to remove the modules, module_utils,
 	Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
 
 	#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
-	#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.).
+	#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
 
 
 Adding the content to the new collection

docs/docsite/rst/dev_guide/developing_modules_best_practices.rst

@@ -135,7 +135,7 @@ Modules must output valid JSON only. Follow these guidelines for creating correc
 * Be consistent about returns (some modules are too random), unless it is detrimental to the state/action.
 * Make returns reusable--most of the time you don't want to read it, but you do want to process it and re-purpose it.
 * Return diff if in diff mode. This is not required for all modules, as it won't make sense for certain ones, but please include it when applicable.
-* Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_ library. Basic python types (strings, int, dicts, lists, etc) are serializable.
+* Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_ library. Basic python types (strings, int, dicts, lists, and so on) are serializable.
 * Do not return an object via exit_json(). Instead, convert the fields you need from the object into the fields of a dictionary and return the dictionary.
 * Results from many hosts will be aggregated at once, so your module should return only relevant output. Returning the entire contents of a log file is generally bad form.
 

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -104,15 +104,15 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 :description:
 
   * A detailed description (generally two or more sentences).
-  * Must be written in full sentences, i.e. with capital letters and periods/full stops.
+  * Must be written in full sentences, in other words, 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, for example, ``version_added: '2.1'``
 
 :author:
 
@@ -178,8 +178,8 @@ 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'``.
+    * Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
+    * This is a string, and not a float, for example, ``version_added: '2.3'``.
 
   :suboptions:
 
@@ -367,8 +367,8 @@ Otherwise, for each value returned, provide the following fields. All fields are
   :sample:
     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'``.
+    Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
+    This is a string, and not a float, for example, ``version_added: '2.3'``.
   :contains:
     Optional. To describe nested return values, set ``type: complex``, ``type: dict``, or ``type: list``/``elements: dict`` and repeat the elements above for each sub-field.
 

docs/docsite/rst/dev_guide/developing_modules_general_aci.rst

@@ -151,13 +151,13 @@ The ``construct_url()`` method takes 2 required arguments:
 * **self** - passed automatically with the class instance
 * **root_class** - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys
 
-  + **aci_class**: The name of the class used by the APIC, e.g. ``fvTenant``
+  + **aci_class**: The name of the class used by the APIC, for example ``fvTenant``
 
-  + **aci_rn**: The relative name of the object, e.g. ``tn-ACME``
+  + **aci_rn**: The relative name of the object, for example ``tn-ACME``
 
-  + **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, e.g. ``{'name': 'ACME'}``
+  + **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, for example ``{'name': 'ACME'}``
 
-  + **module_object**: The particular object for this class, e.g. ``ACME``
+  + **module_object**: The particular object for this class, for example ``ACME``
 
 Example:
 
@@ -220,7 +220,7 @@ The ``aci.payload()`` method is used to build a dictionary of the proposed objec
 
 The ``aci.payload()`` method takes two required arguments and 1 optional argument, depending on if the module manages child objects.
 
-* ``aci_class`` is the APIC name for the object's class, e.g. ``aci_class='fvBD'``
+* ``aci_class`` is the APIC name for the object's class, for example ``aci_class='fvBD'``
 * ``class_config`` is the appropriate dictionary to be used as the payload for the POST request
 
   + The keys should match the names used by the APIC.

docs/docsite/rst/dev_guide/developing_modules_general_windows.rst

@@ -141,7 +141,7 @@ To provision the environment as is, run the following:
 Unlike setting up a single Windows instance with Vagrant, these hosts can also
 be accessed using the IP address directly as well as through the forwarded
 ports. It is easier to access it over the host only network adapter as the
-normal protocol ports are used, e.g. RDP is still over ``3389``. In cases where
+normal protocol ports are used, for example RDP is still over ``3389``. In cases where
 the host cannot be resolved using the host only network IP, the following
 protocols can be access over ``127.0.0.1`` using these forwarded ports:
 
@@ -179,8 +179,8 @@ When creating a new module there are a few things to keep in mind:
 - Ensure the code runs under Powershell v3 and higher on Windows Server 2008 and higher; if higher minimum Powershell or OS versions are required, ensure the documentation reflects this clearly
 - Ansible runs modules under strictmode version 2.0. Be sure to test with that enabled by putting ``Set-StrictMode -Version 2.0`` at the top of your dev script
 - Favor native Powershell cmdlets over executable calls if possible
-- Use the full cmdlet name instead of aliases, e.g. ``Remove-Item`` over ``rm``
-- Use named parameters with cmdlets, e.g. ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp``
+- Use the full cmdlet name instead of aliases, for example ``Remove-Item`` over ``rm``
+- Use named parameters with cmdlets, for example ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp``
 
 A very basic Powershell module `win_environment <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_environment.ps1>`_ incorporates best practices for Powershell modules. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met.
 
@@ -400,7 +400,7 @@ the various modules that call that util.
 
 An example of this would be to have a module util that handles authentication and communication against an API This
 util can be used by multiple modules to expose a common set of module options like the API endpoint, username,
-password, timeout, cert validation, etc, without having to add those options to each module spec.
+password, timeout, cert validation, and so on without having to add those options to each module spec.
 
 The standard convention for a module util that has a shared argument spec would have
 

docs/docsite/rst/dev_guide/developing_program_flow_modules.rst

@@ -63,7 +63,7 @@ values as :term:`JSON`, and various file operations.
 .. note:: In Ansible, up to version 2.0.x, the official Python modules used the
     :ref:`module_replacer` framework.  For module authors, :ref:`Ansiballz` is
     largely a superset of :ref:`module_replacer` functionality, so you usually
-    do not need to know about one versus the other.
+    do not need to understand the differences between them.
 
 .. _flow_powershell_modules:
 

docs/docsite/rst/dev_guide/index.rst

@@ -32,7 +32,7 @@ Find the task that best describes what you want to do:
       * an :ref:`OpenStack module <OpenStack_module_development>`.
       * an :ref:`oVirt/RHV module <oVirt_module_development>`.
       * a :ref:`VMware module <VMware_module_development>`.
-   * 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.).
+   * 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, and so on).
 
 * I want to refine my code:
 

docs/docsite/rst/dev_guide/module_lifecycle.rst

@@ -30,7 +30,7 @@ To deprecate a module, you must:
   :removed_in: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:.
   :remove_by_date: (Added in Ansible 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:.
   :why: Optional string that used to detail why this has been removed.
-  :alternative: Inform users they should do instead, i.e. ``Use M(whatmoduletouseinstead) instead.``.
+  :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``.
 
 * note: with the advent of collections and ``routing.yml`` we might soon require another entry in this file to mark the deprecation.
 

docs/docsite/rst/dev_guide/overview_architecture.rst

@@ -19,7 +19,7 @@ Modules
 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.
 
-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).
+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, and so on).
 
 Module utilities
 ================
@@ -34,7 +34,7 @@ Plugins
 Inventory
 =========
 
-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.
+By default, Ansible represents the machines it manages in a file (INI, YAML, and so on) 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.