diff options
| author | Sandra McCann <samccann@redhat.com> | 2022-11-21 14:39:07 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-11-21 11:39:07 -0800 |
| commit | 548248604d4669c0a4a61920d02375986e5979ab (patch) | |
| tree | f1693d99fe4ec16c95b14b7cab786092537748c6 /docs | |
| parent | fb00aad4143d9ec3cdda9a154b6b25a96ff7a813 (diff) | |
| download | ansible-548248604d4669c0a4a61920d02375986e5979ab.tar.gz | |
Backportapalooza 11 18 (#79416)
* communication.rst: Add IRC channel to Storage WG info (#79374)
(cherry picked from commit 66cc952b4910f0d98073740cac6e261ec3c19290)
* [DOCS] collection_release_with_branches.rst: update major releases section (#79335)
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Don Naro <dnaro@redhat.com>
(cherry picked from commit 6baf25a0489bcb156221cc4656257990c4d65f07)
* Update pull.py (#79387)
(cherry picked from commit b7ea661807449919c36fe60b22a9406258808f7a)
* iss#55935: Documents missing internal parameters and polishes 'Intern… (#79118)
Co-authored-by: Jaroslav Klech <jklech@redhat.com>
Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
(cherry picked from commit 3ae2f97d4a9d55980fad2101f8f5f3e7cf2e0664)
* Clarify that b64decode does not work with binary output (#79294)
(cherry picked from commit f089aae5eef8c11934cb58b8139de004ba89588d)
* Update fileglob.py (#78887)
Improve documentation for relative file paths
(cherry picked from commit 6cec31574f8e19059b447a2d5f4fe5763d721403)
* consolidate duplicated test files (#79380)
(cherry picked from commit a954918b6095adf52c663bdcc340c55762189393)
* communication.rst: add AAP Config As Code WG (#79365)
(cherry picked from commit 35db7df9ce6810e03b55ecada161ac0be6963c33)
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: saranti <tsarantis@proton.me>
Co-authored-by: JaroslavKlech <klechh@gmail.com>
Co-authored-by: Joseph Shraibman <josephks@users.noreply.github.com>
Co-authored-by: seachanged <dll@sonic.net>
Diffstat (limited to 'docs')
9 files changed, 297 insertions, 247 deletions
diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst index d48cb24fee..f8ba7edf37 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst @@ -22,9 +22,13 @@ Releasing major collection versions The new version is assumed to be ``X.0.0``. -1. If you are going to release the ``community.general`` and ``community.network`` collections, create new ``backport-X`` and ``needs_backport_to_stable_X`` labels in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels. +1. Make sure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If that is not the case, create a PR to update it. This will make sanity tests fail for all deprecations that have to be removed in ``X.0.0``, so this is potentially a lot of work and should have been done weeks before the major release. -2. Ensure you are in a default branch in your local fork. These examples use ``main``. +2. Check the collection for deprecations that are planned for removal in the major release that were not reported by the sanity tests. Use past changelogs or run ``grep -r `X.0.0` plugins/`` in the repository. + +3. If you are going to release the ``community.general`` and ``community.network`` collections, create a new ``backport-X`` label in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels. + +4. Ensure you are in a default branch in your local fork. These examples use ``main``. .. code-block:: bash @@ -32,7 +36,7 @@ The new version is assumed to be ``X.0.0``. git checkout main # if needed -3. Update your local fork: +5. Update your local fork: .. code-block:: bash @@ -79,9 +83,17 @@ Creating the changelogs 5. Switch to the ``stable-X`` branch. -6. In the ``stable-X`` branch, ensure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If not, update it. +6. In the ``stable-X`` branch, verify that ``galaxy.yml`` contains the correct version number ``X.0.0``. -7. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.0.0.yml`` with the content: +7. In the ``stable-X`` branch, ensure that ``changelogs/changelog.yml`` contains a correct ancestor's version: + + .. code-block:: yaml + + ancestor: X-1.0.0 + releases: {} + + +8. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.0.0.yml`` with the content: .. code-block:: yaml @@ -90,6 +102,7 @@ Creating the changelogs The format is reStructuredText, but not a list as for regular changelog fragments. This text will be inserted into the changelog. + For example: .. code-block:: yaml @@ -97,18 +110,18 @@ Creating the changelogs release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD. -8. In the ``stable-X`` branch, generate the changelogs: +9. In the ``stable-X`` branch, generate the changelogs: .. code-block:: bash antsibull-changelog release --cummulative-release -9. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected. +10. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected. -10. In the ``stable-X`` branch, update ``README.md`` so that the changelog link points to ``/tree/stable-X/`` and no longer to ``/tree/main/``, and change badges respectively, for example, in case of AZP, add ``?branchName=stable-X`` to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X). +11. In the ``stable-X`` branch, update ``README.md`` so that the changelog link points to ``/tree/stable-X/`` and no longer to ``/tree/main/``, and change badges respectively, for example, in case of AZP, add ``?branchName=stable-X`` to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X). -11. In the ``stable-X`` branch, add, commit, and push changes to ``README.md``, ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the ``origin``. +12. In the ``stable-X`` branch, add, commit, and push changes to ``README.md``, ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the ``origin``. Publishing the collection @@ -123,16 +136,25 @@ Publishing the collection git push upstream NEW_VERSION -2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. +2. If the collection uses `Zuul <https://github.com/ansible/zuul-config/blob/master/README.rst>`_ for publishing its releases, wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. -3. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. +3. If the release tarball did not appear within several hours after pushing the tag, try to re-tag the release commit and push the tag again. In the ``stable-X`` branch being at the release commit: + .. code-block:: bash -4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + git tag --delete NEW_VERSION + git push upstream :NEW_VERSION + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.0.0" + git push upstream NEW_VERSION + + +4. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. + +5. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. -5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. +6. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. -6. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, ``X.1.0``. Add, commit and push to the **upstream** repository. +7. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, ``X.1.0``. Add, commit and push to the **upstream** repository. Releasing minor collection versions diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index d1d95d2fa7..87a37e8618 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -102,6 +102,7 @@ Working groups Many of our community `Working Groups <https://github.com/ansible/community/wiki#working-groups>`_ meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. +- `AAP Configuration as Code <https://github.com/redhat-cop/controller_configuration/wiki/AAP-Configuration-as-Code>`_ - Matrix: `#aap_config_as_code:ansible.com <https://matrix.to/#/#aap_config_as_code:ansible.com>`_ - `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.com <https://matrix.to:/#/#aws:ansible.com>`_ | IRC: ``#ansible-aws`` - `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ (`Security playbooks/roles <https://github.com/ansible/ansible-lockdown>`_) - Matrix: `#lockdown:ansible.com <https://matrix.to:/#/#lockdown:ansible.com>`_ | IRC: ``#ansible-lockdown`` - `AWX Working Group <https://github.com/ansible/awx>`_ - Matrix: `#awx:ansible.com <https://matrix.to:/#/#awx:ansible.com>`_ | IRC: ``#ansible-awx`` @@ -122,7 +123,7 @@ Many of our community `Working Groups <https://github.com/ansible/community/wiki - `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.com <https://matrix.to:/#/#network:ansible.com>`_ | IRC: ``#ansible-network`` - `PostgreSQL Working Group <https://github.com/ansible-collections/community.postgresql/wiki/PostgreSQL-Working-Group>`_ - Matrix: `#postgresql:ansible.com <https://matrix.to:/#/#postgresql:ansible.com>`_ - `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` -- `Storage Working Group <https://github.com/ansible/community/wiki/Storage>`_ - Matrix: `#storage:ansible.com <https://matrix.to/#/#storage:ansible.com>`_ +- `Storage Working Group <https://github.com/ansible/community/wiki/Storage>`_ - Matrix: `#storage:ansible.com <https://matrix.to/#/#storage:ansible.com>`_ | IRC: ``#ansible-storage`` - `Testing Working Group <https://github.com/ansible/community/wiki/Testing>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` - `VMware Working Group <https://github.com/ansible/community/wiki/VMware>`_ - Matrix: `#vmware:ansible.com <https://matrix.to:/#/#vmware:ansible.com>`_ | IRC: ``#ansible-vmware`` - `Windows Working Group <https://github.com/ansible/community/wiki/Windows>`_ - Matrix: `#windows:ansible.com <https://matrix.to:/#/#windows:ansible.com>`_ | IRC: ``#ansible-windows`` diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index 82ffaf3c19..d896c544f2 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -114,7 +114,7 @@ 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 +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, read and parse the parameters, operate on the data, and print its return data @@ -173,7 +173,7 @@ 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 +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 a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>` @@ -279,12 +279,12 @@ substitutions: 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 + 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 need this you should instantiate an `AnsibleModule` and then use :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. + from a comma-separated string of file system names to an actual python + list of file system 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 @@ -322,7 +322,7 @@ importing a module. This lets Ansible run both the wrapper script and the module * 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. + 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 @@ -378,79 +378,69 @@ 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 Ansible 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 -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. +Ansible features. Modules often do not need to know about these explicitly because +the features are implemented in :py:mod:`ansible.module_utils.basic`. However, certain +features need support from modules and some knowledge of the internal arguments is useful. + +The internal arguments in this section 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. -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 ^^^^^^^^^^^^^^^ -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`. +Type: ``bool`` + +Set to ``True`` whenever an argument in a task or play specifies ``no_log``. Any module that calls the :py:meth:`AnsibleModule.log` function handles this action automatically. If you have a module that implements its own logging then you need to check the value of ``_ansible_no_log``. To access ``_ansible_no_log`` in a module, instantiate the ``AnsibleModule`` utility and then check the value of :attr:`AnsibleModule.no_log`. .. note:: - ``no_log`` specified in a module's argument_spec is handled by a different mechanism. + ``no_log`` specified in a module's ``argument_spec`` is handled by a different mechanism. + _ansible_debug -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^ + +Type: ``bool`` + +Operates verbose logging and logging of external commands that a module executes. If the module uses the :py:meth:`AnsibleModule.debug` function rather than the :py:meth:`AnsibleModule.log` function then the messages are only logged if you set the ``_ansible_debug`` argument to ``True``. To access ``_ansible_debug`` in a module, instantiate the ``AnsibleModule`` utility and access :attr:`AnsibleModule._debug`. For more details, see :ref:`DEFAULT_DEBUG`. -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 ``_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 -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^ + +Type: ``bool`` + +With this parameter you can configure your module to show a unified diff of changes that will be applied to the templated files. To access ``_ansible_diff`` in a module, instantiate the ``AnsibleModule`` utility and access :attr:`AnsibleModule._diff`. You can also access this parameter using the ``diff`` keyword in your playbook, or the relevant environment variable. For more details, see :ref:`playbook_keywords` and the :ref:`DIFF_ALWAYS` configuration option. -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 ^^^^^^^^^^^^^^^^^^ -Unused. This value could be used for finer grained control over logging. +Type: ``int`` + +You can use this argument to control the level (0 for none) of verbosity in logging. + _ansible_selinux_special_fs ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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`: +Type: ``list`` +Elements: ``strings`` -.. code-block:: ini +This argument provides modules with the names of file systems which should have a special SELinux context. They are used by the ``AnsibleModule`` methods which operate on files (changing attributes, moving, and copying). - # ansible.cfg - [selinux] - special_context_filesystems=nfs,vboxsf,fuse,ramfs,vfat +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 file systems, instantiate ``AnsibleModule`` and examine the list in :attr:`AnsibleModule._selinux_special_fs`. -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. +This argument replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from :ref:`module_replacer`. In the module replacer framework the argument was formatted as a comma-separated string of file system names. Under the Ansiballz framework it is a list. You can access ``_ansible_selinux_special_fs`` using the corresponding environment variable. For more details, see the :ref:`DEFAULT_SELINUX_SPECIAL_FS` configuration option. .. versionadded:: 2.1 + _ansible_syslog_facility ^^^^^^^^^^^^^^^^^^^^^^^^ -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 -`AnsibleModule` and then retrieve the name of the syslog facility from -:attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less hacky than the old :ref:`module_replacer` code: +This argument controls which syslog facility the module logs to. Most modules should just use the :meth:`AnsibleModule.log` function which will then make use of this. If a module has to use this on its own, it should instantiate the ``AnsibleModule`` method and then retrieve the name of the syslog facility from :attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less elegant than the :ref:`module_replacer` code: .. code-block:: python @@ -464,20 +454,77 @@ this. If a module has to use this on its own, it should instantiate an facility = getattr(syslog, facility_name, syslog.LOG_USER) syslog.openlog(NAME, 0, facility) +For more details, see the :ref:`DEFAULT_SYSLOG_FACILITY` configuration option. + .. versionadded:: 2.1 + _ansible_version ^^^^^^^^^^^^^^^^ -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 -:attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from -:ref:`module_replacer`. +This argument passes the version of Ansible to the module. To access it, a module should instantiate the ``AnsibleModule`` method and then retrieve the version from :attr:`AnsibleModule.ansible_version`. This replaces :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from :ref:`module_replacer`. .. versionadded:: 2.1 +_ansible_module_name +^^^^^^^^^^^^^^^^^^^^ + +Type: ``str`` + +This argument passes the information to modules about their name. For more details see, the configuration option :ref:`DEFAULT_MODULE_NAME`. + + +_ansible_string_conversion_action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This argument provides instructions about what modules should do after the values of the user-specified module parameters are converted to strings. For more details, see the :ref:`STRING_CONVERSION_ACTION` configuration option. + + +_ansible_keep_remote_files +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Type: ``bool`` + +This argument provides instructions that modules must be ready if they need to keep the remote files. For more details, see the :ref:`DEFAULT_KEEP_REMOTE_FILES` configuration option. + + +_ansible_socket +^^^^^^^^^^^^^^^ +This argument provides modules with a socket for persistent connections. The argument is created using the :ref:`PERSISTENT_CONTROL_PATH_DIR` configuration option. + + +_ansible_shell_executable +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Type: ``bool`` + +This argument ensures that modules use the designated shell executable. For more details, see the :ref:`ansible_shell_executable` remote host environment parameter. + + +_ansible_tmpdir +^^^^^^^^^^^^^^^ + +Type: ``str`` + +This argument provides instructions to modules that all commands must use the designated temporary directory, if created. The action plugin designs this temporary directory. + +Modules can access this parameter by using the public ``tmpdir`` property. The ``tmpdir`` property will create a temporary directory if the action plugin did not set the parameter. + +The directory name is generated randomly, and the the root of the directory is determined by one of these: + +* :ref:`DEFAULT_LOCAL_TMP` +* `remote_tmp <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_ +* `system_tmpdirs <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-system_tmpdirs>`_ + +As a result, using the ``ansible.cfg`` configuration file to activate or customize this setting will not guarantee that you control the full value. + + +_ansible_remote_tmp +^^^^^^^^^^^^^^^^^^^ + +The module's ``tmpdir`` property creates a randomized directory name in this directory if the action plugin did not set ``_ansible_tmpdir``. For more details, see the `remote_tmp <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_ parameter of the shell plugin. + + .. _flow_module_return_values: Module return values & Unsafe strings diff --git a/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst b/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst index 8595d98621..9424bda8ab 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst @@ -1,6 +1,24 @@ +.. _testing_pep8: + pep8 ==== Python static analysis for PEP 8 style guideline compliance. -See :ref:`testing_pep8` for more information. +`PEP 8`_ style guidelines are enforced by `pycodestyle`_ on all python files in the repository by default. + +Running locally +----------------- + +The `PEP 8`_ check can be run locally as follows: + +.. code-block:: shell + + ansible-test sanity --test pep8 [file-or-directory-path-to-check] ... + + + +.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ +.. _pycodestyle: https://pypi.org/project/pycodestyle/ + + diff --git a/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst b/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst index efb58f2095..dcb78c0527 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst @@ -1,6 +1,140 @@ +.. _testing_validate-modules: + validate-modules ================ Analyze modules for common issues in code and documentation. -See :ref:`testing_validate-modules` for more information. +.. contents:: + :local: + +Usage +------ + +.. code:: shell + + cd /path/to/ansible/source + source hacking/env-setup + ansible-test sanity --test validate-modules + +Help +----- + +Type ``ansible-test sanity validate-modules -h`` to display help for using this sanity test. + + + +Extending validate-modules +--------------------------- + +The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``. + + +Codes +------ + +============================================================ ================== ==================== ========================================================================================= + **Error Code** **Type** **Level** **Sample Message** +------------------------------------------------------------ ------------------ -------------------- ----------------------------------------------------------------------------------------- + ansible-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier Ansible version + collection-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier collection version + ansible-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier Ansible version + ansible-module-not-initialized Syntax Error Execution of the module did not result in initialization of AnsibleModule + collection-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier collection version + deprecated-date Documentation Error A date before today appears as ``removed_at_date`` or in ``deprecated_aliases`` + deprecation-mismatch Documentation Error Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places. + doc-choices-do-not-match-spec Documentation Error Value for "choices" from the argument_spec does not match the documentation + doc-choices-incompatible-type Documentation Error Choices value from the documentation is not compatible with type defined in the argument_spec + doc-default-does-not-match-spec Documentation Error Value for "default" from the argument_spec does not match the documentation + doc-default-incompatible-type Documentation Error Default value from the documentation is not compatible with type defined in the argument_spec + doc-elements-invalid Documentation Error Documentation specifies elements for argument, when "type" is not ``list``. + doc-elements-mismatch Documentation Error Argument_spec defines elements different than documentation does + doc-missing-type Documentation Error Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``) + doc-required-mismatch Documentation Error argument in argument_spec is required but documentation says it is not, or vice versa + doc-type-does-not-match-spec Documentation Error Argument_spec defines type different than documentation does + documentation-error Documentation Error Unknown ``DOCUMENTATION`` error + documentation-syntax-error Documentation Error Invalid ``DOCUMENTATION`` schema + illegal-future-imports Imports Error Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``. + import-before-documentation Imports Error Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` + import-error Documentation Error ``Exception`` attempting to import module for ``argument_spec`` introspection + import-placement Locations Warning Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` + imports-improper-location Imports Error Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` + incompatible-choices Documentation Error Choices value from the argument_spec is not compatible with type defined in the argument_spec + incompatible-default-type Documentation Error Default value from the argument_spec is not compatible with type defined in the argument_spec + invalid-argument-name Documentation Error Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used internally by Ansible Core Engine + invalid-argument-spec Documentation Error Argument in argument_spec must be a dictionary/hash when used + invalid-argument-spec-options Documentation Error Suboptions in argument_spec are invalid + invalid-documentation Documentation Error ``DOCUMENTATION`` is not valid YAML + invalid-documentation-markup Documentation Error ``DOCUMENTATION`` or ``RETURN`` contains invalid markup + invalid-documentation-options Documentation Error ``DOCUMENTATION.options`` must be a dictionary/hash when used + invalid-examples Documentation Error ``EXAMPLES`` is not valid YAML + invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules + invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error + invalid-removal-version Documentation Error The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a `semantic version <https://semver.org/>`_) + invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1 + missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing + missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing + missing-documentation Documentation Error No ``DOCUMENTATION`` provided + missing-examples Documentation Error No ``EXAMPLES`` provided + missing-gplv3-license Documentation Error GPLv3 license header not found + missing-module-utils-basic-import Imports Warning Did not find ``ansible.module_utils.basic`` import + missing-module-utils-import-csharp-requirements Imports Error No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found + missing-powershell-interpreter Syntax Error Interpreter line is not ``#!powershell`` + missing-python-interpreter Syntax Error Interpreter line is not ``#!/usr/bin/python`` + missing-return Documentation Error No ``RETURN`` documentation provided + missing-return-legacy Documentation Warning No ``RETURN`` documentation provided for legacy module + missing-suboption-docs Documentation Error Argument in argument_spec has sub-options but documentation does not define sub-options + module-incorrect-version-added Documentation Error Module level ``version_added`` is incorrect + module-invalid-version-added Documentation Error Module level ``version_added`` is not a valid version number + module-utils-specific-import Imports Error ``module_utils`` imports should import specific components, not ``*`` + multiple-utils-per-requires Imports Error ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement + multiple-csharp-utils-per-requires Imports Error Ansible C# util requirements do not support multiple utils per statement + no-default-for-required-parameter Documentation Error Option is marked as required but specifies a default. Arguments with a default should not be marked as required + no-log-needed Parameters Error Option name suggests that the option contains a secret value, while ``no_log`` is not specified for this option in the argument spec. If this is a false positive, explicitly set ``no_log=False`` + nonexistent-parameter-documented Documentation Error Argument is listed in DOCUMENTATION.options, but not accepted by the module + option-incorrect-version-added Documentation Error ``version_added`` for new option is incorrect + option-invalid-version-added Documentation Error ``version_added`` for option is not a valid version number + parameter-invalid Documentation Error Argument in argument_spec is not a valid python identifier + parameter-invalid-elements Documentation Error Value for "elements" is valid only when value of "type" is ``list`` + implied-parameter-type-mismatch Documentation Error Argument_spec implies ``type="str"`` but documentation defines it as different data type + parameter-type-not-in-doc Documentation Error Type value is defined in ``argument_spec`` but documentation doesn't specify a type + parameter-alias-repeated Parameters Error argument in argument_spec has at least one alias specified multiple times in aliases + parameter-alias-self Parameters Error argument in argument_spec is specified as its own alias + parameter-documented-multiple-times Documentation Error argument in argument_spec with aliases is documented multiple times + parameter-list-no-elements Parameters Error argument in argument_spec "type" is specified as ``list`` without defining "elements" + parameter-state-invalid-choice Parameters Error Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice. Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module. + python-syntax-error Syntax Error Python ``SyntaxError`` while parsing module + removal-version-must-be-major Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0) + return-syntax-error Documentation Error ``RETURN`` is not valid YAML, ``RETURN`` fragments missing or invalid + return-invalid-version-added Documentation Error ``version_added`` for return value is not a valid version number + subdirectory-missing-init Naming Error Ansible module subdirectories must contain an ``__init__.py`` + try-except-missing-has Imports Warning Try/Except ``HAS_`` expression missing + undocumented-parameter Documentation Error Argument is listed in the argument_spec, but not documented in the module + unidiomatic-typecheck Syntax Error Type comparison using ``type()`` found. Use ``isinstance()`` instead + unknown-doc-fragment Documentation Warning Unknown pre-existing ``DOCUMENTATION`` error + use-boto3 Imports Error ``boto`` import found, new modules should use ``boto3`` + use-fail-json-not-sys-exit Imports Error ``sys.exit()`` call found. Should be ``exit_json``/``fail_json`` + use-module-utils-urls Imports Error ``requests`` import found, should use ``ansible.module_utils.urls`` instead + use-run-command-not-os-call Imports Error ``os.call`` used instead of ``module.run_command`` + use-run-command-not-popen Imports Error ``subprocess.Popen`` used instead of ``module.run_command`` + use-short-gplv3-license Documentation Error GPLv3 license header should be the :ref:`short form <copyright>` for new modules + mutually_exclusive-type Documentation Error mutually_exclusive entry contains non-string value + mutually_exclusive-collision Documentation Error mutually_exclusive entry has repeated terms + mutually_exclusive-unknown Documentation Error mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?) + required_one_of-type Documentation Error required_one_of entry contains non-string value + required_one_of-collision Documentation Error required_one_of entry has repeated terms + required_one_of-unknown Documentation Error required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?) + required_together-type Documentation Error required_together entry contains non-string value + required_together-collision Documentation Error required_together entry has repeated terms + required_together-unknown Documentation Error required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?) + required_if-is_one_of-type Documentation Error required_if entry has a fourth value which is not a bool + required_if-requirements-type Documentation Error required_if entry has a third value (requirements) which is not a list or tuple + required_if-requirements-collision Documentation Error required_if entry has repeated terms in requirements + required_if-requirements-unknown Documentation Error required_if entry's requirements contains option which does not appear in argument_spec (potentially an alias of an option?) + required_if-unknown-key Documentation Error required_if entry's key does not appear in argument_spec (potentially an alias of an option?) + required_if-key-in-requirements Documentation Error required_if entry contains its key in requirements list/tuple + required_if-value-type Documentation Error required_if entry's value is not of the type specified for its key + required_by-collision Documentation Error required_by entry has repeated terms + required_by-unknown Documentation Error required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?) + version-added-must-be-major-or-minor Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0) +============================================================ ================== ==================== ========================================================================================= diff --git a/docs/docsite/rst/dev_guide/testing_pep8.rst b/docs/docsite/rst/dev_guide/testing_pep8.rst index 7c19b2a13d..c634914dff 100644 --- a/docs/docsite/rst/dev_guide/testing_pep8.rst +++ b/docs/docsite/rst/dev_guide/testing_pep8.rst @@ -1,25 +1,8 @@ :orphan: -.. _testing_pep8: ***** PEP 8 ***** -.. contents:: Topics - -`PEP 8`_ style guidelines are enforced by `pycodestyle`_ on all python files in the repository by default. - -Running Locally -=============== - -The `PEP 8`_ check can be run locally with: - -.. code-block:: shell - - ansible-test sanity --test pep8 [file-or-directory-path-to-check] ... - - - -.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ -.. _pycodestyle: https://pypi.org/project/pycodestyle/ +This page has moved to :ref:`testing_pep8`.
\ No newline at end of file diff --git a/docs/docsite/rst/dev_guide/testing_validate-modules.rst b/docs/docsite/rst/dev_guide/testing_validate-modules.rst index b937df599e..1c74fe39b1 100644 --- a/docs/docsite/rst/dev_guide/testing_validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing_validate-modules.rst @@ -1,165 +1,7 @@ :orphan: -.. _testing_validate-modules: - **************** validate-modules **************** -.. contents:: Topics - -Python program to help test or validate Ansible modules. - -``validate-modules`` is one of the ``ansible-test`` Sanity Tests, see :ref:`testing_sanity` for more information. - -Originally developed by Matt Martz (@sivel) - - -Usage -===== - -.. code:: shell - - cd /path/to/ansible/source - source hacking/env-setup - ansible-test sanity --test validate-modules - -Help -==== - -.. code:: shell - - usage: validate-modules [-h] [-w] [--exclude EXCLUDE] [--arg-spec] - [--base-branch BASE_BRANCH] [--format {json,plain}] - [--output OUTPUT] - modules [modules ...] - - positional arguments: - modules Path to module or module directory - - optional arguments: - -h, --help show this help message and exit - -w, --warnings Show warnings - --exclude EXCLUDE RegEx exclusion pattern - --arg-spec Analyze module argument spec - --base-branch BASE_BRANCH - Used in determining if new options were added - --format {json,plain} - Output format. Default: "plain" - --output OUTPUT Output location, use "-" for stdout. Default "-" - - -Extending validate-modules -========================== - -The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``. - - -Codes -===== - -============================================================ ================== ==================== ========================================================================================= - **Error Code** **Type** **Level** **Sample Message** ------------------------------------------------------------- ------------------ -------------------- ----------------------------------------------------------------------------------------- - ansible-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier Ansible version - collection-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier collection version - ansible-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier Ansible version - ansible-module-not-initialized Syntax Error Execution of the module did not result in initialization of AnsibleModule - collection-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier collection version - deprecated-date Documentation Error A date before today appears as ``removed_at_date`` or in ``deprecated_aliases`` - deprecation-mismatch Documentation Error Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places. - doc-choices-do-not-match-spec Documentation Error Value for "choices" from the argument_spec does not match the documentation - doc-choices-incompatible-type Documentation Error Choices value from the documentation is not compatible with type defined in the argument_spec - doc-default-does-not-match-spec Documentation Error Value for "default" from the argument_spec does not match the documentation - doc-default-incompatible-type Documentation Error Default value from the documentation is not compatible with type defined in the argument_spec - doc-elements-invalid Documentation Error Documentation specifies elements for argument, when "type" is not ``list``. - doc-elements-mismatch Documentation Error Argument_spec defines elements different than documentation does - doc-missing-type Documentation Error Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``) - doc-required-mismatch Documentation Error argument in argument_spec is required but documentation says it is not, or vice versa - doc-type-does-not-match-spec Documentation Error Argument_spec defines type different than documentation does - documentation-error Documentation Error Unknown ``DOCUMENTATION`` error - documentation-syntax-error Documentation Error Invalid ``DOCUMENTATION`` schema - illegal-future-imports Imports Error Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``. - import-before-documentation Imports Error Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` - import-error Documentation Error ``Exception`` attempting to import module for ``argument_spec`` introspection - import-placement Locations Warning Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` - imports-improper-location Imports Error Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` - incompatible-choices Documentation Error Choices value from the argument_spec is not compatible with type defined in the argument_spec - incompatible-default-type Documentation Error Default value from the argument_spec is not compatible with type defined in the argument_spec - invalid-argument-name Documentation Error Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used internally by Ansible Core Engine - invalid-argument-spec Documentation Error Argument in argument_spec must be a dictionary/hash when used - invalid-argument-spec-options Documentation Error Suboptions in argument_spec are invalid - invalid-documentation Documentation Error ``DOCUMENTATION`` is not valid YAML - invalid-documentation-markup Documentation Error ``DOCUMENTATION`` or ``RETURN`` contains invalid markup - invalid-documentation-options Documentation Error ``DOCUMENTATION.options`` must be a dictionary/hash when used - invalid-examples Documentation Error ``EXAMPLES`` is not valid YAML - invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules - invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error - invalid-removal-version Documentation Error The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a `semantic version <https://semver.org/>`_) - invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1 - missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing - missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing - missing-documentation Documentation Error No ``DOCUMENTATION`` provided - missing-examples Documentation Error No ``EXAMPLES`` provided - missing-gplv3-license Documentation Error GPLv3 license header not found - missing-module-utils-basic-import Imports Warning Did not find ``ansible.module_utils.basic`` import - missing-module-utils-import-csharp-requirements Imports Error No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found - missing-powershell-interpreter Syntax Error Interpreter line is not ``#!powershell`` - missing-python-interpreter Syntax Error Interpreter line is not ``#!/usr/bin/python`` - missing-return Documentation Error No ``RETURN`` documentation provided - missing-return-legacy Documentation Warning No ``RETURN`` documentation provided for legacy module - missing-suboption-docs Documentation Error Argument in argument_spec has sub-options but documentation does not define sub-options - module-incorrect-version-added Documentation Error Module level ``version_added`` is incorrect - module-invalid-version-added Documentation Error Module level ``version_added`` is not a valid version number - module-utils-specific-import Imports Error ``module_utils`` imports should import specific components, not ``*`` - multiple-utils-per-requires Imports Error ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement - multiple-csharp-utils-per-requires Imports Error Ansible C# util requirements do not support multiple utils per statement - no-default-for-required-parameter Documentation Error Option is marked as required but specifies a default. Arguments with a default should not be marked as required - no-log-needed Parameters Error Option name suggests that the option contains a secret value, while ``no_log`` is not specified for this option in the argument spec. If this is a false positive, explicitly set ``no_log=False`` - nonexistent-parameter-documented Documentation Error Argument is listed in DOCUMENTATION.options, but not accepted by the module - option-incorrect-version-added Documentation Error ``version_added`` for new option is incorrect - option-invalid-version-added Documentation Error ``version_added`` for option is not a valid version number - parameter-invalid Documentation Error Argument in argument_spec is not a valid python identifier - parameter-invalid-elements Documentation Error Value for "elements" is valid only when value of "type" is ``list`` - implied-parameter-type-mismatch Documentation Error Argument_spec implies ``type="str"`` but documentation defines it as different data type - parameter-type-not-in-doc Documentation Error Type value is defined in ``argument_spec`` but documentation doesn't specify a type - parameter-alias-repeated Parameters Error argument in argument_spec has at least one alias specified multiple times in aliases - parameter-alias-self Parameters Error argument in argument_spec is specified as its own alias - parameter-documented-multiple-times Documentation Error argument in argument_spec with aliases is documented multiple times - parameter-list-no-elements Parameters Error argument in argument_spec "type" is specified as ``list`` without defining "elements" - parameter-state-invalid-choice Parameters Error Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice. Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module. - python-syntax-error Syntax Error Python ``SyntaxError`` while parsing module - removal-version-must-be-major Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0) - return-syntax-error Documentation Error ``RETURN`` is not valid YAML, ``RETURN`` fragments missing or invalid - return-invalid-version-added Documentation Error ``version_added`` for return value is not a valid version number - subdirectory-missing-init Naming Error Ansible module subdirectories must contain an ``__init__.py`` - try-except-missing-has Imports Warning Try/Except ``HAS_`` expression missing - undocumented-parameter Documentation Error Argument is listed in the argument_spec, but not documented in the module - unidiomatic-typecheck Syntax Error Type comparison using ``type()`` found. Use ``isinstance()`` instead - unknown-doc-fragment Documentation Warning Unknown pre-existing ``DOCUMENTATION`` error - use-boto3 Imports Error ``boto`` import found, new modules should use ``boto3`` - use-fail-json-not-sys-exit Imports Error ``sys.exit()`` call found. Should be ``exit_json``/``fail_json`` - use-module-utils-urls Imports Error ``requests`` import found, should use ``ansible.module_utils.urls`` instead - use-run-command-not-os-call Imports Error ``os.call`` used instead of ``module.run_command`` - use-run-command-not-popen Imports Error ``subprocess.Popen`` used instead of ``module.run_command`` - use-short-gplv3-license Documentation Error GPLv3 license header should be the :ref:`short form <copyright>` for new modules - mutually_exclusive-type Documentation Error mutually_exclusive entry contains non-string value - mutually_exclusive-collision Documentation Error mutually_exclusive entry has repeated terms - mutually_exclusive-unknown Documentation Error mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?) - required_one_of-type Documentation Error required_one_of entry contains non-string value - required_one_of-collision Documentation Error required_one_of entry has repeated terms - required_one_of-unknown Documentation Error required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?) - required_together-type Documentation Error required_together entry contains non-string value - required_together-collision Documentation Error required_together entry has repeated terms - required_together-unknown Documentation Error required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?) - required_if-is_one_of-type Documentation Error required_if entry has a fourth value which is not a bool - required_if-requirements-type Documentation Error required_if entry has a third value (requirements) which is not a list or tuple - required_if-requirements-collision Documentation Error required_if entry has repeated terms in requirements - required_if-requirements-unknown Documentation Error required_if entry's requirements contains option which does not appear in argument_spec (potentially an alias of an option?) - required_if-unknown-key Documentation Error required_if entry's key does not appear in argument_spec (potentially an alias of an option?) - required_if-key-in-requirements Documentation Error required_if entry contains its key in requirements list/tuple - required_if-value-type Documentation Error required_if entry's value is not of the type specified for its key - required_by-collision Documentation Error required_by entry has repeated terms - required_by-unknown Documentation Error required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?) - version-added-must-be-major-or-minor Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0) -============================================================ ================== ==================== ========================================================================================= +This page has moved to :ref:`testing_validate-modules`. diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index d52f3a708c..a049ef0f1c 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -14,6 +14,7 @@ Config paths By default these should be relative to the config file, some are specifically relative to the current working directory or the playbook and should have this noted in their description. Things like ssh keys are left to use the current working directory because it mirrors how the underlying tools would use it. +.. _playbook_task_paths: Task paths ========== diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 1b5a7d1bde..6063c061ae 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -2061,6 +2061,8 @@ As of version 2.6, you can define the type of encoding to use, the default is `` .. note:: The ``string`` filter is only required for Python 2 and ensures that text to encode is a unicode string. Without that filter before b64encode the wrong value will be encoded. +.. note:: The return value of b64decode is a string. If you decrypt a binary blob using b64decode and then try to use it (for example by using :ref:`copy <copy_module>` to write it to a file) you will mostly likely find that your binary has been corrupted. If you need to take a base64 encoded binary and write it to disk, it is best to use the system ``base64`` command with the :ref:`shell module <shell_module>`, piping in the encoded data using the ``stdin`` parameter. For example: ``shell: cmd="base64 --decode > myfile.bin" stdin="{{ encoded }}"`` + .. versionadded:: 2.6 Managing UUIDs |