diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst index de59be659f2..124505859f2 100644 --- a/docs/docsite/rst/community/contributor_path.rst +++ b/docs/docsite/rst/community/contributor_path.rst @@ -61,7 +61,15 @@ You can find some ideas on how you can contribute in :ref:`how_can_i_help`. If you are interested in contributing to collections, take a look at :ref:`collection contributions` and the `collection repository `_'s ``README`` and ``CONTRIBUTING`` files. To make your first experience as smooth as possible, read the repository documentation carefully, then ask the repository maintainers for guidance if you have any questions. -You can also look for GitHub issues labeled with the ``easyfix``, ``good_first_issue``, and ``docs`` labels. Add a comment on the GitHub issue to say you are looking at it and to ask for help if you need it. +Take a look at GitHub issues labeled with the ``easyfix`` and ``good_first_issue`` labels for: + +- `Ansible collections repositories `_ +- `All other Ansible projects `_ + +Issues labeled with the ``docs`` label in `Ansible collections `_ and `other `_ Ansible projects can be also good to start with. + +When you choose an issue to work on, add a comment directly on the GitHub issue to say you are looking at it and let others know to avoid conflicting work. +You can also ask for help in a comment if you need it. Continue to contribute ====================== diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 51f30b7c3b2..0f464f117e0 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -35,14 +35,28 @@ To submit a documentation PR from docs.ansible.com with ``Edit on GitHub``: #. Be patient while Ansibot, our automated script, adds labels, pings the docs maintainers, and kicks off a CI testing run. #. Keep an eye on your PR - the docs team may ask you for changes. -Reviewing open PRs and issues -============================= +Reviewing or solving open issues +================================ + +Review or solve open documentation issues for: + +- `Ansible projects `_ +- `Ansible collections `_ + +Reviewing open PRs +================== + +Review open documentation pull requests for: + +- Ansible `projects `_ +- Ansible `collections `_ -You can also contribute by reviewing open documentation `issues `_ and `PRs `_. To add a helpful review, please: +To add a helpful review, please: -- Include a comment - "looks good to me" only helps if we know why. -- For issues, reproduce the problem. -- For PRs, test the change. +- Test the change if applicable. +- Think if it can be made better (including wording, structure, fixing typos and so on). +- Suggest improvements. +- Approve the change with the ``looks good to me`` comment. Opening a new issue and/or PR ============================= diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst index 66f55d1898c..38cb1db8d2a 100644 --- a/docs/docsite/rst/community/how_can_I_help.rst +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -61,6 +61,14 @@ Review and submit pull requests As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`development process ` to learn how to get your code accepted into Ansible. +You can also get started with solving GitHub issues labeled with the ``easyfix`` and ``good_first_issue`` labels for: + +- `Ansible collections `_ +- `All other Ansible projects `_ + +When you choose an issue to work on, add a comment directly on the GitHub issue to say you are looking at it and let others know to avoid conflicting work. +You can also ask for help in a comment if you need it. + Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file `_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternatively, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection. Become a collection maintainer diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index 7228f8c83d2..43a0e69619c 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -20,7 +20,7 @@ In general, collection maintainers: - Review and commit changes made by other contributors. - :ref:`Backport ` changes to stable branches. - Address or assign issues to appropriate contributors. -- Release collections. +- :ref:`Release collections `. - Ensure that collections adhere to the `Collection Requirements `_, - Track changes announced in `News for collection contributors and maintainers `_ and update a collection in accordance with these changes. - Subscribe and submit news to the `Bullhorn newsletter `_. diff --git a/docs/docsite/rst/dev_guide/ansible_index.rst b/docs/docsite/rst/dev_guide/ansible_index.rst index 5e79df45141..a660df06e57 100644 --- a/docs/docsite/rst/dev_guide/ansible_index.rst +++ b/docs/docsite/rst/dev_guide/ansible_index.rst @@ -36,8 +36,7 @@ Find the task that best describes what you want to do: * a :ref:`network module ` * a :ref:`Windows module `. * an :ref:`Amazon module `. - * an :ref:`OpenStack module `. - * an :ref:`oVirt/RHV module `. + * an :ref:`oVirt/RHV module `. * a :ref:`VMware module `. * I want to :ref:`write a series of related modules ` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on). @@ -77,12 +76,6 @@ If you prefer to read the entire guide, here's a list of the pages in order. developing_modules_documenting sidecar developing_modules_general_windows - developing_modules_general_aci - platforms/aws_guidelines - platforms/openstack_guidelines - platforms/ovirt_dev_guide - platforms/vmware_guidelines - platforms/vmware_rest_guidelines developing_modules_in_groups testing module_lifecycle diff --git a/docs/docsite/rst/dev_guide/core_index.rst b/docs/docsite/rst/dev_guide/core_index.rst index 00a7db63c4f..3c2fdb73d46 100644 --- a/docs/docsite/rst/dev_guide/core_index.rst +++ b/docs/docsite/rst/dev_guide/core_index.rst @@ -73,7 +73,6 @@ If you prefer to read the entire guide, here's a list of the pages in order. developing_modules_documenting sidecar developing_modules_general_windows - developing_modules_general_aci developing_modules_in_groups testing module_lifecycle diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst b/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst deleted file mode 100644 index 0c9826d0e44..00000000000 --- a/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst +++ /dev/null @@ -1,454 +0,0 @@ -.. _aci_dev_guide: - -**************************** -Developing Cisco ACI modules -**************************** -This is a brief walk-through of how to create new Cisco ACI modules for Ansible. - -For more information about Cisco ACI, look at the :ref:`Cisco ACI user guide `. - -What's covered in this section: - -.. contents:: - :depth: 3 - :local: - - -.. _aci_dev_guide_intro: - -Introduction -============ -The `cisco.aci collection `_ already includes a large number of Cisco ACI modules, however the ACI object model is huge and covering all possible functionality would easily cover more than 1500 individual modules. - -If you need specific functionality, you have 2 options: - -- Learn the ACI object model and use the low-level APIC REST API using the :ref:`aci_rest ` module -- Write your own dedicated modules, which is actually quite easy - -.. seealso:: - - `Ansible ACI collection `_ - Github repository of the ansible ACI collection - :ref:`hacking_collections` - Information on how to contribute to collections. - `ACI Fundamentals: ACI Policy Model `_ - A good introduction to the ACI object model. - `APIC Management Information Model reference `_ - Complete reference of the APIC object model. - `APIC REST API Configuration Guide `_ - Detailed guide on how the APIC REST API is designed and used, incl. many examples. - - -So let's look at how a typical ACI module is built up. - - -.. _aci_dev_guide_module_structure: - -ACI module structure -==================== - -Importing objects from Python libraries ---------------------------------------- -The following imports are standard across ACI modules: - -.. code-block:: python - - from ansible.module_utils.aci import ACIModule, aci_argument_spec - from ansible.module_utils.basic import AnsibleModule - - -Defining the argument spec --------------------------- -The first line adds the standard connection parameters to the module. After that, the next section will update the ``argument_spec`` dictionary with module-specific parameters. The module-specific parameters should include: - -* the object_id (usually the name) -* the configurable properties of the object -* the parent object IDs (all parents up to the root) -* only child classes that are a 1-to-1 relationship (1-to-many/many-to-many require their own module to properly manage) -* the state - - + ``state: absent`` to ensure object does not exist - + ``state: present`` to ensure the object and configs exist; this is also the default - + ``state: query`` to retrieve information about objects in the class - -.. code-block:: python - - def main(): - argument_spec = aci_argument_spec() - argument_spec.update( - object_id=dict(type='str', aliases=['name']), - object_prop1=dict(type='str'), - object_prop2=dict(type='str', choices=['choice1', 'choice2', 'choice3']), - object_prop3=dict(type='int'), - parent_id=dict(type='str'), - child_object_id=dict(type='str'), - child_object_prop=dict(type='str'), - state=dict(type='str', default='present', choices=['absent', 'present', 'query']), - ) - - -.. hint:: Do not provide default values for configuration arguments. Default values could cause unintended changes to the object. - -Using the AnsibleModule object ------------------------------- -The following section creates an AnsibleModule instance. The module should support check-mode, so we pass the ``argument_spec`` and ``supports_check_mode`` arguments. Since these modules support querying the APIC for all objects of the module's class, the object/parent IDs should only be required if ``state: absent`` or ``state: present``. - -.. code-block:: python - - module = AnsibleModule( - argument_spec=argument_spec, - supports_check_mode=True, - required_if=[ - ['state', 'absent', ['object_id', 'parent_id']], - ['state', 'present', ['object_id', 'parent_id']], - ], - ) - - -Mapping variable definition ---------------------------- -Once the AnsibleModule object has been initiated, the necessary parameter values should be extracted from ``params`` and any data validation should be done. Usually the only params that need to be extracted are those related to the ACI object configuration and its child configuration. If you have integer objects that you would like to validate, then the validation should be done here, and the ``ACIModule.payload()`` method will handle the string conversion. - -.. code-block:: python - - object_id = object_id - object_prop1 = module.params['object_prop1'] - object_prop2 = module.params['object_prop2'] - object_prop3 = module.params['object_prop3'] - if object_prop3 is not None and object_prop3 not in range(x, y): - module.fail_json(msg='Valid object_prop3 values are between x and (y-1)') - child_object_id = module.params['child_object_id'] - child_object_prop = module.params['child_object_prop'] - state = module.params['state'] - - -Using the ACIModule object --------------------------- -The ACIModule class handles most of the logic for the ACI modules. The ACIModule extends functionality to the AnsibleModule object, so the module instance must be passed into the class instantiation. - -.. code-block:: python - - aci = ACIModule(module) - -The ACIModule has six main methods that are used by the modules: - -* construct_url -* get_existing -* payload -* get_diff -* post_config -* delete_config - -The first two methods are used regardless of what value is passed to the ``state`` parameter. - -Constructing URLs -^^^^^^^^^^^^^^^^^ -The ``construct_url()`` method is used to dynamically build the appropriate URL to interact with the object, and the appropriate filter string that should be appended to the URL to filter the results. - -* When the ``state`` is not ``query``, the URL is the base URL to access the APIC plus the distinguished name to access the object. The filter string will restrict the returned data to just the configuration data. -* When ``state`` is ``query``, the URL and filter string used depends on what parameters are passed to the object. This method handles the complexity so that it is easier to add new modules and so that all modules are consistent in what type of data is returned. - -.. note:: Our design goal is to take all ID parameters that have values, and return the most specific data possible. If you do not supply any ID parameters to the task, then all objects of the class will be returned. If your task does consist of ID parameters sed, then the data for the specific object is returned. If a partial set of ID parameters are passed, then the module will use the IDs that are passed to build the URL and filter strings appropriately. - -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, for example ``fvTenant`` - - + **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, for example ``{'name': 'ACME'}`` - - + **module_object**: The particular object for this class, for example ``ACME`` - -Example: - -.. code-block:: python - - aci.construct_url( - root_class=dict( - aci_class='fvTenant', - aci_rn='tn-{0}'.format(tenant), - target_filter={'name': tenant}, - module_object=tenant, - ), - ) - -Some modules, like ``aci_tenant``, are the root class and so they would not need to pass any additional arguments to the method. - -The ``construct_url()`` method takes 4 optional arguments, the first three imitate the root class as described above, but are for child objects: - -* subclass_1 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys - - + Example: Application Profile Class (AP) - -* subclass_2 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys - - + Example: End Point Group (EPG) - -* subclass_3 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys - - + Example: Binding a Contract to an EPG - -* child_classes - The list of APIC names for the child classes supported by the modules. - - + This is a list, even if it is a list of one - + These are the unfriendly names used by the APIC - + These are used to limit the returned child_classes when possible - + Example: ``child_classes=['fvRsBDSubnetToProfile', 'fvRsNdPfxPol']`` - -.. note:: Sometimes the APIC will require special characters ([, ], and -) or will use object metadata in the name ("vlanns" for VLAN pools); the module should handle adding special characters or joining of multiple parameters in order to keep expected inputs simple. - -Getting the existing configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once the URL and filter string have been built, the module is ready to retrieve the existing configuration for the object: - -* ``state: present`` retrieves the configuration to use as a comparison against what was entered in the task. All values that are different than the existing values will be updated. -* ``state: absent`` uses the existing configuration to see if the item exists and needs to be deleted. -* ``state: query`` uses this to perform the query for the task and report back the existing data. - -.. code-block:: python - - aci.get_existing() - - -When state is present -^^^^^^^^^^^^^^^^^^^^^ -When ``state: present``, the module needs to perform a diff against the existing configuration and the task entries. If any value needs to be updated, then the module will make a POST request with only the items that need to be updated. Some modules have children that are in a 1-to-1 relationship with another object; for these cases, the module can be used to manage the child objects. - -Building the ACI payload -"""""""""""""""""""""""" -The ``aci.payload()`` method is used to build a dictionary of the proposed object configuration. All parameters that were not provided a value in the task will be removed from the dictionary (both for the object and its children). Any parameter that does have a value will be converted to a string and added to the final dictionary object that will be used for comparison against the existing configuration. - -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, 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. - + The values should be the corresponding value in ``module.params``; these are the variables defined above - -* ``child_configs`` is optional, and is a list of child config dictionaries. - - + The child configs include the full child object dictionary, not just the attributes configuration portion. - + The configuration portion is built the same way as the object. - -.. code-block:: python - - aci.payload( - aci_class=aci_class, - class_config=dict( - name=bd, - descr=description, - type=bd_type, - ), - child_configs=[ - dict( - fvRsCtx=dict( - attributes=dict( - tnFvCtxName=vrf - ), - ), - ), - ], - ) - - -Performing the request -"""""""""""""""""""""" -The ``get_diff()`` method is used to perform the diff, and takes only one required argument, ``aci_class``. -Example: ``aci.get_diff(aci_class='fvBD')`` - -The ``post_config()`` method is used to make the POST request to the APIC if needed. This method doesn't take any arguments and handles check mode. -Example: ``aci.post_config()`` - - -Example code -"""""""""""" -.. code-block:: text - - if state == 'present': - aci.payload( - aci_class='', - class_config=dict( - name=object_id, - prop1=object_prop1, - prop2=object_prop2, - prop3=object_prop3, - ), - child_configs=[ - dict( - ''=dict( - attributes=dict( - child_key=child_object_id, - child_prop=child_object_prop - ), - ), - ), - ], - ) - - aci.get_diff(aci_class='') - - aci.post_config() - - -When state is absent -^^^^^^^^^^^^^^^^^^^^ -If the task sets the state to absent, then the ``delete_config()`` method is all that is needed. This method does not take any arguments, and handles check mode. - -.. code-block:: text - - elif state == 'absent': - aci.delete_config() - - -Exiting the module -^^^^^^^^^^^^^^^^^^ -To have the module exit, call the ACIModule method ``exit_json()``. This method automatically takes care of returning the common return values for you. - -.. code-block:: text - - aci.exit_json() - - if __name__ == '__main__': - main() - - -.. _aci_dev_guide_testing: - -Testing ACI library functions -============================= -You can test your ``construct_url()`` and ``payload()`` arguments without accessing APIC hardware by using the following python script: - -.. code-block:: text - - #!/usr/bin/python - import json - from ansible.module_utils.network.aci.aci import ACIModule - - # Just another class mimicking a bare AnsibleModule class for construct_url() and payload() methods - class AltModule(): - params = dict( - host='dummy', - port=123, - protocol='https', - state='present', - output_level='debug', - ) - - # A sub-class of ACIModule to overload __init__ (we don't need to log into APIC) - class AltACIModule(ACIModule): - def __init__(self): - self.result = dict(changed=False) - self.module = AltModule() - self.params = self.module.params - - # Instantiate our version of the ACI module - aci = AltACIModule() - - # Define the variables you need below - aep = 'AEP' - aep_domain = 'uni/phys-DOMAIN' - - # Below test the construct_url() arguments to see if it produced correct results - aci.construct_url( - root_class=dict( - aci_class='infraAttEntityP', - aci_rn='infra/attentp-{}'.format(aep), - target_filter={'name': aep}, - module_object=aep, - ), - subclass_1=dict( - aci_class='infraRsDomP', - aci_rn='rsdomP-[{}]'.format(aep_domain), - target_filter={'tDn': aep_domain}, - module_object=aep_domain, - ), - ) - - # Below test the payload arguments to see if it produced correct results - aci.payload( - aci_class='infraRsDomP', - class_config=dict(tDn=aep_domain), - ) - - # Print the URL and proposed payload - print 'URL:', json.dumps(aci.url, indent=4) - print 'PAYLOAD:', json.dumps(aci.proposed, indent=4) - - -This will result in: - -.. code-block:: yaml - - URL: "https://dummy/api/mo/uni/infra/attentp-AEP/rsdomP-[phys-DOMAIN].json" - PAYLOAD: { - "infraRsDomP": { - "attributes": { - "tDn": "phys-DOMAIN" - } - } - } - -Testing for sanity checks -------------------------- -For legacy versions of ansible, you can run from your fork something like: - -.. code-block:: bash - - $ ansible-test sanity --python 2.7 lib/ansible/modules/network/aci/aci_tenant.py - -Meanwhile, the ACI modules have moved into a collection. Please refer to the links below, which provide detailed guidance -how to setup your environment and test the collection. - -.. seealso:: - - :ref:`hacking_collections` - Information how to setup your environment to contribute to collections - :ref:`testing_sanity` - Information on how to build sanity tests. - `Ansible ACI collection `_ - Github repository of the ansible ACI collection - - -Testing ACI integration tests ------------------------------ -You can run this: - -.. code-block:: bash - - $ ansible-test network-integration --continue-on-error --allow-unsupported --diff -v aci_tenant - -.. note:: You may need to add ``--python 2.7`` or ``--python 3.6`` in order to use the correct python version for performing tests. - -You may want to edit the used inventory at *test/integration/inventory.networking* and add something like: - -.. code-block:: ini - - [aci:vars] - aci_hostname=my-apic-1 - aci_username=admin - aci_password=my-password - aci_use_ssl=yes - aci_use_proxy=no - - [aci] - localhost ansible_ssh_host=127.0.0.1 ansible_connection=local - -.. seealso:: - - :ref:`testing_integration` - Information on how to build integration tests. - - -Testing for test coverage -------------------------- -You can run this: - -.. code-block:: bash - - $ ansible-test network-integration --python 2.7 --allow-unsupported --coverage aci_tenant - $ ansible-test coverage report diff --git a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst deleted file mode 100644 index 208aed539e5..00000000000 --- a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _AWS_module_development: - -**************************************************** -Guidelines for Ansible Amazon AWS module development -**************************************************** - -This guide has moved to :ref:`ansible_collections.amazon.aws.docsite.dev_guide_intro`. diff --git a/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst deleted file mode 100644 index b4b91b44503..00000000000 --- a/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _OpenStack_module_development: - -OpenStack Ansible Modules -========================= - -Please see the `OpenStack guidelines `_, for further information. diff --git a/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst b/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst deleted file mode 100644 index 4316bce5cfb..00000000000 --- a/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _oVirt_module_development: - -oVirt Ansible Modules -===================== - - -See the `ovirt.ovirt collection documentation `_ for details on how to contribute to this collection. \ No newline at end of file diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst deleted file mode 100644 index dc05302d6f5..00000000000 --- a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _VMware_module_development: - -****************************************************** -Guidelines for VMware module development -****************************************************** - -This guide has moved to :ref:`ansible_collections.community.vmware.docsite.vmware_ansible_devguide`. diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst deleted file mode 100644 index c176dfdbc38..00000000000 --- a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _VMware_REST_module_development: - -********************************************* -Guidelines for VMware REST module development -********************************************* - -This guide has moved to :ref:`ansible_collections.vmware.vmware_rest.docsite.vmware_rest_devguide`. diff --git a/docs/docsite/rst/reference_appendices/test_strategies.rst b/docs/docsite/rst/reference_appendices/test_strategies.rst index 8ed20accd38..fa28f76b7f0 100644 --- a/docs/docsite/rst/reference_appendices/test_strategies.rst +++ b/docs/docsite/rst/reference_appendices/test_strategies.rst @@ -176,11 +176,20 @@ This is the great culmination of embedded tests: ansible.builtin.command: /usr/bin/take_out_of_pool {{ inventory_hostname }} delegate_to: 127.0.0.1 - roles: + tasks: - - common - - webserver - - apply_testing_checks + - ansible.builtin.include_role: + name: "{{ item }}" + loop: + - common + - webserver + + - name: run any notified handlers + ansible.builtin.meta: flush_handlers + + - name: test the configuration + ansible.builtin.include_role: + name: apply_testing_checks post_tasks: diff --git a/lib/ansible/plugins/doc_fragments/files.py b/lib/ansible/plugins/doc_fragments/files.py index 2356bd72ce6..b87fd11d102 100644 --- a/lib/ansible/plugins/doc_fragments/files.py +++ b/lib/ansible/plugins/doc_fragments/files.py @@ -36,6 +36,8 @@ options: - Name of the user that should own the filesystem object, as would be fed to I(chown). - When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. + - Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. + type: str group: description: diff --git a/lib/ansible/plugins/filter/combine.yml b/lib/ansible/plugins/filter/combine.yml index f2f43718395..86788f31079 100644 --- a/lib/ansible/plugins/filter/combine.yml +++ b/lib/ansible/plugins/filter/combine.yml @@ -36,7 +36,6 @@ EXAMPLES: | # ab => {'a':1, 'b':3, 'c': 4} ab: {{ {'a':1, 'b':2} | combine({'b':3, 'c':4}) }} - # ab => {'a':1, 'b':3, 'c': 4} many: "{{ dict1 | combine(dict2, dict3, dict4) }}" RETURN: