Select a reference Windows module for the documentation

[dagwieers]

ISSUE TYPE

• Documentation Report

COMPONENT NAME

win_environment

ANSIBLE VERSION

v2.4

SUMMARY

As discussed on IRC, let's declare one module the reference module for Windows and use it in the documentation for new module authors.

The module should have all these features:

• must be small in business logic
• must be idempotent
• must support check-mode
• must include -validateset
• must include -failifempty
• must include -default
• must include a bool-type parameter
• should include a path-type parameter
• should include a string-type parameter

The win_service module was our first candidate, but it has turned into a more complex example. It does meet all requirements. So we decided to use win_environment as the reference module.

The rewrite of this module and the expected bikeshedding will be done during the review-process in the PR. The PR will also include:

• Include plenty of annotations to guide the new contributor
• Ensure the module has a consistent CodingStyle that we prefer most (but we do not enforce it) @jborean93
• We update this module every time we improve our standards, so that new and existing maintainers can track new standards

[dagwieers]

@jhawkesworth @nitzmahone @dav1x @jctanner As discussed on IRC.

[jhawkesworth]

mention @ilpianista who also mentioned on IRC

some other (unsorted) thoughts

what to put for metadata?
link to jimic's presentation(s) on writing modules?
a note about | out-null so you don't put unintended objects into the output pipelines (therefore putting cruft into the generated json.
avoid feeding trailing slashes on strings into ConvertTo-Json 'cos it makes it fail
link to how to run existing integration tests against your test windows machines/vms

[gundalow]

Keep me in the loop, will help with the developing_modules.html rewrite that's going on.

[jhawkesworth]

more thoughts...

need to support powershell 3 and above
links to powershell references

document return values
conventions for var names
conventions for return values
check with linux equivalents to make consistent names where possible, but only if it makes sense

advanced topics:

example of calling .net class
example of embedding c# code

[dagwieers]

So we have 3 candidates, and win_service is no longer on the table :-)

[dag@moria ansible.git]$ grep -l -- '-type "str"' $(grep -l -- '-type "path"' $(grep -l -- '-type "bool"' $(grep -l default $(grep -l failifempty $(grep -l 'validateset' $(grep -rl '$check_mode' lib/ansible/modules/windows/))))))
lib/ansible/modules/windows/win_lineinfile.ps1
lib/ansible/modules/windows/win_owner.ps1
lib/ansible/modules/windows/win_uri.ps1

Of these, win_uri is clearly the most simple example, although it does have some things that require cleaning up.

• headers should be a dict (implement a dict-type !)
• fix the idempotency issue when writing to a file
• make it somewhat more feature complete with the uri module
• reorganize result
• add integration tests
• update documentation

So quite some work before we can consider it first-of-class.

[dagwieers]

It has been decided to use win_environment as it has the most simple implementation of an idempotent module supporting check-mode and diff support.

The upside is that we don't need to do a lot of work ;-)

[jhawkesworth]

At 19:00 UTC on Tuesday 19 September 2017 this ticket will be processed during the second Windows Sprint,
https://github.com/ansible/community/wiki/Windows:-sprints
we would appreciate if you could join the Sprint to help out with understanding/fixing/closing this issue.

[dagwieers]

We looked into this issue today, and two things are required moving forward:

1. We need to update the win_environment module to follow the latest conventions done
2. We need to update the docs to point at this module as the reference module done