New collection microsoft.iis

[jborean93]

We have a new certified collection microsoft.iis which is going to replace the community.windows.win_iis_* modules (deprecation still needs to happen for those). These are Windows/PowerShell based modules and have no Ansible side dependencies.

Ansible Galaxy: https://galaxy.ansible.com/microsoft/iis
GitHub: https://github.com/ansible-collections/microsoft.iis
Issues Tracker: https://github.com/ansible-collections/microsoft.iis/issues
GitHub Handles: @jborean93, @Yaish25491
Is the collection part of Automation Hub: Yes
We meet Collection Requirements: Yes

[gundalow]

Thanks for raising this request.

Are these new modules backwards compatible with those from community.windows?

[jborean93]

Not fully backwards compatible. We have written a migration guide for each or the community modules to the ones in this collection https://ansible-collections.github.io/microsoft.iis/branch/main/collections/microsoft/iis/docsite/guide_migration.html.

As they aren’t backwards compatible we won’t be creating a redirect but will instead deprecate the community ones in a future release.

[gundalow]

Makes sense
I like the migration guide.

@felixfontein @samccann once this progressed though inclusion process we should think how we can extend the existing documentation (for old and new) to help people migrate there playbooks.

One specific thing will be to manually update the module docs for the old modules to link to the new ones, manually as there will not be a redirect, only a depreciation.

[Andersson007]

@jborean93 hello, thanks for submitting the collection for inclusion!

Ansible Collections Checklist (short version)

For details about the following points, refer to the Collection Requirements.

Every comment should say whether the reviewer expects it to be addressed, or whether it's optional.

Note for reviewers: If you don't know how to check any of the points below, please ask maintainers of the collection you're reviewing or a Steering Committee member for clarifications in comments of corresponding inclusion discussion.

Public availability and communication:

• published on Ansible Galaxy with version 1.0.0 or later
• have a Code of Conduct (CoC) compatible with the Ansible Code of Conduct (CoC)
• have a publicly available issue tracker that does not require a paid level of service to create an account or view issues
• have a public git repository
• releases of the collection are tagged in its repository

Standards and documentation:

• adheres to semantic versioning
• follows licensing rules
• follows the Ansible documentation standards and the style guide
  • SHOULD FIX: format macros like C() don't seem to work under the requirements doc field which results in C(IISAdministration) PowerShell module on Galaxy
  • MUST FIX: - name: task description fields must not end with dots, colons, etc.
  • MUST FIX: invalid documentation format which results in errors on Galaxy, please make the format standard
  • MUST FIX: some examples are incorrect, e.g. a module name is missing (i guess because of the non-standard formatting they appear in the descriptions)
  • COMMENT: maybe ansible-test sanity doesn't work correctly against the docs because it doesn't perceive the files as doc files?
• follows development conventions; as well as these other requirements:
  • modules satisfy the concept of idempotency
  • modules that only gather information are named <something>_info
  • modules that return ansible_facts are named <something>_facts and do not return non-facts
  • other modules must not allow querying information using specific state option values, or similar mechanisms (like state=get or state=query). These features should be moved to <something>_info or <something>_fact modules.
  • check_mode is supported in all _info and _facts modules
• supports all Python versions supported by all ansible-core versions its supports. If it does not, read the full guidelines to see if you qualify for an exception and document the unsupported Python versions in the collection README.md and in every module and plugin (or in doc fragments)
• only uses the allowed plugin types in the plugins/ directory
• has README.md
• FQCNs are used for all plugins and modules including ansible.builtin. for builtin ones from ansible-core in all their appearances in the documentation, examples, and return sections, and in extends_documentation_fragment:s.
• documentation and return sections use version_added: containing the collection version for which an option, module or plugin was added (except cases when they were added in the very first release of the collection)
• public plugins, roles and playbooks do not use files outside of meta/, plugins/, roles/, and playbooks/

Collection management:

• galaxy.yml having tags field set
• collection dependencies must have a lower bound on the version which is at least 1.0.0, and are all part of the ansible package
• meta/runtime.yml defines the minimal version of Ansible which the collection works with
• has changelog, preferably with changelogs/changelog.yaml
• collection repository should not contain any large objects (binaries) comparatively to the current Galaxy tarball size limit of 20 MB. For example, package installers for testing purposes shouldn't be added.
• collection repository should not contain any unnecessary files like, for example, temporary files. Temporary files should be added to .gitignore.

Tests:

Note for reviewers: If you don't know how to check the points below, please ask maintainers of the collection you're reviewing how you can do it.

• In most cases, CI is set up via GitHub Actions.
• Check .yml files in the .github/workflows directory. There must be at least the sanity section under jobs containing the ansible-test sanity command running against all supported ansible-core versions that must be also listed there, for example, - stable-2.15, - stable-2.16, - stable-2.17.
• Check workflow runs by clicking the Actions tab in the repository's page - you're interested in Scheduled runs, runs against release commits and runs against pull requests.
• If there are no workflows in the Actions tab, ask the collection maintainers how CI is implemented.

• passed ansible-test sanity
• if test/sanity/ignore*.txt exists, it MUST not contain error codes listed in the list of errors that must not be ignored
  COMMENT: noticed that all the files are empty, maybe remove?
• has CI tests up and running against each of the "major versions" of ansible-base/ansible-core that the collection supports
• all CI tests MUST run against every pull request
• all CI tests MUST run regularly (nightly, or at least once per week)
• sanity tests MUST run against a commit that releases the collection; if they don't pass, the collection won't be released

[felixfontein]

Docs rendering on Galaxy is very basic and has quite a lot of bugs. I have reported at least one serious problem more than a year ago and never even got any reaction to it.

I'd completely ignore docs on Galaxy for that reason. It's often Galaxy's docs viewer that's broken, not the docs.

[Andersson007]

Ah, let's ignore it then (though it's pity). @jborean93 please let us know one all what can be fixed is fixed, thanks

[jborean93]

I've fixed up the C() in requirements and some of the example tasks ending with . in ansible-collections/microsoft.iis#25. The other issues seem related to the way Galaxy is rendering the docs and while there has been some work to improve the support for sidecar docs (ansible/galaxy-importer#329) it'll take time to filter into production and be used there. The docs do seem to be rendered properly with the community Ansible docs based on the artifact from the PR and what can be seen in the latest commit page https://ansible-collections.github.io/microsoft.iis/branch/main/.

Hopefully that covers what was missing but let me know if there were any other issues I may have missed.

[jborean93]

@Andersson007 just an FYI Galaxy (and AH) have pushed a new version with the latest galaxy-importer version and is able to render sidecar documentation correctly. I've also found the reason why it failed to render such modules and opened a PR on the UI repo to fix it ansible/ansible-hub-ui#5471 but in the meantime there is a workaround available so they should all be render as of the 1.0.2 release.

There is now a further bug where modules entries are duplicated in the UI but that's mostly a cosmetic problem IMO which we can hopefully fix in a future release of galaxy-importer.

[Andersson007]

@jborean93 thanks for the info!
@ansible-collections/steering-committee could anybody please to a quick review as in the comment?

[Andersson007]

@jborean93 thanks for fixing the stuff! I've marked that docs item as resolved and have put "Second review needed"
Could anybody from the @ansible-collections/steering-committee conduct the second short review, i.e. to check only the following:

• follows the Ansible documentation standards and the style guide
• follows development conventions; as well as these other requirements:
  • modules satisfy the concept of idempotency
  • modules that only gather information are named <something>_info
  • modules that return ansible_facts are named <something>_facts and do not return non-facts
  • other modules must not allow querying information using specific state option values, or similar mechanisms (like state=get or state=query). These features should be moved to <something>_info or <something>_fact modules.
  • check_mode is supported in all _info and _facts modules

[gundalow]

Only spotted a small copy-paste issue with docs links, ansible-collections/microsoft.iis#30

[Andersson007]

@gundalow thanks! I've just started the process in the forum topic

[felixfontein]

I can't say much about the code since it's PowerShell, but I did look a bit at the documentation and noticed that it uses the outdated way (I(...) or C(...)) to markup options, instead of using semantic markup (O(...)). Examples:

• https://github.com/ansible-collections/microsoft.iis/blob/main/plugins/modules/web_application.yml#L22
• https://github.com/ansible-collections/microsoft.iis/blob/main/plugins/modules/web_application_info.yml#L127
• https://github.com/ansible-collections/microsoft.iis/blob/main/plugins/modules/website.yml#L23
• https://github.com/ansible-collections/microsoft.iis/blob/main/plugins/modules/virtual_directory.yml#L38

(Likely there are more.)

Also URLs are not always wrapped in U(...) in documentation, and descriptions not always contain complete sentences (https://github.com/ansible-collections/microsoft.iis/blob/main/plugins/modules/website_info.yml#L16).

The RST documentation also manually composes references to modules instead of using :ansplugin: (https://github.com/ansible-collections/microsoft.iis/blob/main/docs/docsite/rst/guide_migration.rst?plain=1#L33).

In the CI I noticed that it runs unit tests, but there aren't any, so it's basically a no-op. Since the collection does not have Python content, I would completely remove tests/unit/ and the unit tests from the AZP CI matrix. (That also saves RH some money ;).)

Besides these things it looks good - except possibly the module code since I didn't check it.

[jborean93]

instead of using semantic markup (O(...)

I was not aware of these new formats, will go through and update them.

I'll also try and fix up the U(...) and other documentation problems mentions.

I would completely remove tests/unit/ and the unit tests from the AZP CI matrix

Can do, I mostly kept it there in case we ever start adding some other plugins but it's not the end of the world to re-add it back in when needed.

[felixfontein]

You can also comment out the jobs in .azure-pipelines/azure-pipelines.yml, simliar to https://github.com/ansible-collections/community.general/blob/main/.azure-pipelines/azure-pipelines.yml#L361. That way they are easy to re-add but don't run in CI.

[jborean93]

Thanks for looking through it all and sharing the links, ansible-collections/microsoft.iis#26 should have fixed your findings but please let me know if I've missed anything.

[russoz]

Hi @jborean93

Those are in the link provided before, but more specifically in the section about semantic markup:
https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation