Raise the bar for module `DOCUMENTAION`
This validator update was used to find the issues in https://github.com/ansible/ansible/pull/22297/files
**Validation**
* Updated Validation and docs to enforce more (items fixed in https://github.com/ansible/ansible/pull/22297/files)
* Use `suboptions` to document complex options
* Validate module name
* Validate deprecated modules have correct ANSIBLE_METADATA
**Module Documentation Generation**
* Document `suboptions:` Example https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718
* Tidy up HTML generation (valid HTML, no empty lists, etc)
**Documentation**
* Clarify the steps for deprecating a module
* Use correct RST headings
* Document `suboptions:` (options)
* Document `contains:` (returns)
**Details**
The aim is to get this (and corresponding module updates) complete by the time `devel` becomes `2.4`, as this allows us to raise the bar for new modules
Example `suboptions` https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718
The aim is to get this PR integrated into `devel` *before* we branch `stable-2.3`, this will allows us to:
* Raise the bar for new modules in 2.4
* Ensure the generated module documentation for 2.3 and higher is improved, important as we will be doing versioned docs moving forward.
This commit also adds a new test script (ansible-var-precedence-check.py in code-smell/)
to provide us with another line of defense against precedence bugs going forward.
The precedence docs state that the INI vars have a lower precedence than group/host
vars files for inventory and playbooks, however that has not been the case since 2.0
was released. This change fixes that in one way, though not exactly as the docs say.
The rules are:
1) INI/script < inventory dir < playbook dir
2) "all" group vars < other group_vars < host_vars
So the new order will be (from the test script mentioned above):
8. pb_host_vars_file - var in playbook/host_vars/host
9. ini_host_vars_file - var in inventory/host_vars/host
10. ini_host - host var inside the ini
11. pb_group_vars_file_child - var in playbook/group_vars/child
12. ini_group_vars_file_child - var in inventory/group_vars/child
13. pb_group_vars_file_parent - var in playbook/group_vars/parent
14. ini_group_vars_file_parent - var in inventory/group_vars/parent
15. pb_group_vars_file_all - var in playbook/group_vars/all
16. ini_group_vars_file_all - var in inventory/group_vars/all
17. ini_child - child group var inside the ini
18. ini_parent - parent group var inside the ini
19. ini_all - all group var inside the ini
Fixes#21845
- Tests are run to completion instead of stopping on first failure.
- Test results are now parsed instead of passing through to the console.
- Test results can be saved in junit xml format.
- Test results will show up on the Shippable "Tests" result tab.
- Added an experimental --lint option for easier integration with other tools.
- Code smell tests are now usable with the --list-tests, --test and --skip-test options.
- Code split out from executor.py into sanity.py.
- Rename download-logs to download.py and add support for test and coverage results.
- Miscellaneous improvements.
* Make more use of AWS Exception information
* Use pythonic dict assignments
* Improve documentation formatting to make option names clearer
in descriptions
* Meet ansible line length requirements
* Tidy up flake8 messages
Changes include:
- Use Get-AnsibleParam with -type/-validateset
- Replace $result PSObject with normal hash
- Deprecate 'upgrade' parameter by using state=latest
added new base class for file based cache plugins as 99% of code was common
now also catches unexpected decoding exceptions
allows per module file modes and encoding
moved jsonfile code to base
* Fix string formatting
* Provide better tracebacks
* When options is None and extends_documentation_fragment is in use, add an error that options must be a dict
* If options was specified and not a dict, then error
* #19587: refactor to PEP8
* Issue: #19587: add skip_broken option to yum module
PNTSYSOPS-1901 - internal reference
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* Issue: #19587: fix line break, attempt to make readble
things at line 646 look ugly ..
trying to make them look a bit more human readble
though the entire approach should be rewriten
PNTSYSOPS-1901 - internal reference
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* #19587: fixing typo, skip-broken has to be passed as list
* PR: #21475: peer review changes
relates to: revert comment deletion https://github.com/ansible/ansible/pull/21475#discussion_r101574146
relates to: remove irelevant var https://github.com/ansible/ansible/pull/21475#discussion_r101573388
relates to: reformat https://github.com/ansible/ansible/pull/21475#discussion_r101572840
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* PR: #21475: peer review changes
relates to: https://github.com/ansible/ansible/pull/21475#discussion_r101573736
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* Issue: #21475: fixing typo in the Man section
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* PR: #21475 - Peer review: revert variable a
Relates to: https://github.com/ansible/ansible/pull/21475#pullrequestreview-22404868
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* Issue: 19587 - small correction
Signed-off-by: Veaceslav Mindru <vmindru@redhat.com> <mindruv@gmail.com>
* Re-enable module comparisons, specifically for new module detection and for finding new options/arguments
* Only do new module checks in shippable, local will display warning
If versioning is not enabled, then `get_bucket_versioning`
can return an empty dict.
If that happens, the code to enable versioning should still
run!
The logic for suspending versioning was also incorrect, so
have updated that too.
Fixes#20491
* Add tests for `get_fqdn_and_port` method.
Currently tests verify original behavior - returning default `ssh-keyscan` port
Add test around `add_host_key` to verify underlying command arguments
Add some new expectations for `get_fqdn_and_port`
Test that non-standard port is passed to `ssh-keyscan` command
* Ensure ssh hostkey checks respect server port
ssh-keyscan will default to getting the host key for port 22.
If the ssh service is running on a different port, ssh-keyscan
will need to know this.
Tidy up minor flake8 issues
* Update known_hosts tests for port being None
Ensure that git urls don't try and set port when a path
is specified
Update known_hosts tests to meet flake8
* Fix stdin swap context for test_known_hosts
Move test_known_hosts from under basic, as it is its own library.
Remove module_utils.known_hosts from pep8 legacy files list
The f5 module utils were using a file name that appeared to
conflict with the f5 python SDK's namespace. This patch just changes
the name of the included class to be f5_utils to avoid the issue
of namespace collisions
* Skip pep8 analysis when --explain is used.
* Fix return type annotations.
* Match line length requirement of PEP 8 config.
* Consider module_utils deps when running tests.
* Make unused redhat_subscriptions do something
rhsm_baseurl/server_insecure were module params that were
never used previously. Hook them up for register options.
* pep8/style cleanups
* Set a module scope SUBMAN_CMD before we ref it as a global
* move ansible imports to top, remove '*' imports
* remove redhat_subscriptions from pep8 legacy
- centralized skipping
- also fixed module name broken by previous refactor
- let action modules handle async processing
- moved async into base action class's module exec
- action plugins can now run final action as async
- actually skip copy if base skips
- fixed normal for new paths
- ensure internal stat is never async
- default poll to 10 as per docs
- added hint for callback fix on poll
- restructured late tmp, now a pipeline query
- moving action handler to connection as networking does
- fixed network assumption invocation is always passed
- centralized key cleanup, normalized internal var
- _supress_tmpdir_delete now in _ansible_xxx and gets removed from results
- delay internal key removal till after we use em
- nicer tmp removing, using existing methods
- moved cleanup tmp flag to mking tmp func
* Move gather_facts action outside of vmware_guest module
* Move facts gathering method to vmware.py library
* vmware_guest use some vmware.py library methods
* vmware.py lib: fix some PEP 8 issues
* Move snapshot actions to vmware_guest_snapshot
* Move common snapshot facts to vmware.py library
At the moment, this change will use EPoll on Linux, KQueue on *BSDs,
etc, so it should alleviate problems with too many open file
descriptors.
* Bundle a copy of selectors2 so that we have the selectors API everywhere.
* Add licensing information to selectors2 file so it's clear what the
licensing terms and conditions are.
* Exclude the bundled copy of selectors2 from our boilerplate code-smell test
* Rewrite ssh_run tests to attempt to work around problem with mocking
select on shippable
Fixes#14143
* Update validate-modules
* Validates ANSIBLE_METADATA
* Ensures imports happen after documentation vars
* Some pep8 cleanup
* Clean up some left over unneeded code
* Update modules for new module guidelines and validate-modules checks
* Update imports for ec2_vpc_route_table and ec2_vpc_nat_gateway
This version just gets the relevant paths from PluginLoader and then
uses the existing imp.find_plugin() calls in the AnsiballZ code to load
the proper module_utils.
Modify PluginLoader to optionally omit subdirectories (module_utils
needs to operate on top level dirs, not on subdirs because it has
a hierarchical namespace whereas all other plugins use a flat
namespace).
Rename snippet* variables to module_utils*
Add a small number of unittests for recursive_finder
Add a larger number of integration tests to demonstrate that
module_utils is working.
Whitelist module-style shebang in test target library dirs
Prefix module_data variable with b_ to be clear that it holds bytes data
Print out the data that fails to validate when doing
schema checking on modules
This allows easier interpretation of error messages.
From:
```
ERROR: DOCUMENTATION.notes.2: expected basestring
```
To:
```
ERROR: DOCUMENTATION.notes.2: expected basestring @ data['notes'][2].
Got {"As with C(include) this task can be static or dynamic, If static
it implies that it won't need templating nor loops nor conditionals and
will show included tasks in the --list options. Ansible will try to
autodetect what is needed, but you can set `static": 'yes|no` at task
level to control this.'}
```
* Code smell test for iteritems and itervalues
* Change the keydict object in authorized_keys so it doesn't throw a false postive
keydict is a bad data structure anyway. We don't use the iteritems and
itervalues methods so just disable them so that the code-smell tests do
not trigger on it.
* Change release templates so they work with py3
This allows validate-modules to run in an environment where
python 3 is the default. This will no longer be necessary once
validate-modules is updated to work with both python 2 and 3.
- Remove shebangs from:
- ini files
- unit tests
- module_utils
- plugins
- module_docs_fragments
- non-executable Makefiles
- Change non-modules from '/usr/bin/python' to '/usr/bin/env python'.
- Change '/bin/env' to '/usr/bin/env'.
Also removed main functions from unit tests (since they no longer
have a shebang) and fixed a python 3 compatibility issue with
update_bundled.py so it does not need to specify a python 2 shebang.
A script was added to check for unexpected shebangs in files.
This script is run during CI on Shippable.
- Correct directory name in test/README.md
- Move code-smell tests to test/sanity/code-smell
- Update code-smell.sh to use new script paths
- Add test/integration/target-prefixes.win for ansible-test
- Move module unit tests to match module directory layout
John R Barker