Including sensu.sensu_go collections into Ansible 3.0.0

[tadeboro]

Ansible Galaxy: https://galaxy.ansible.com/sensu/sensu_go
GitHub repo: https://github.com/sensu/sensu-go-ansible
Issue tracker: https://github.com/sensu/sensu-go-ansible/issues
Contacts: @tadeboro and @mancabizjak
CI/CD: https://app.circleci.com/pipelines/github/sensu/sensu-go-ansible (one needs to have a CircleCI account to see this, but the account is free and users authenticate using their GitHub or BitBucket account)

We used the issue 236 to track the progress of our collection compliance with the requirements (contains a list of things we checked).

Do note that some of the things from that checklist are not yet released to the galaxy. Why? Because @tadeboro is lazy and would rather avoid doing two releases if anything needs to be updated to pass the review.

One thing that may need a bit of an explanation is our large set of ignores. Our ignore files contain quite a few entries (compile and import checks on python 2.6). But there is a reason for this: the Sensu Go Ansible Collection does not support Python 2.6. And while we can (and indeed do) limit sanity tests to only run on supported Python versions, the Automation Hub import process runs sanity tests on all Python versions in the testing container, including Python 2.6. The partner engineering team said that while those errors are not fatal for certifying a collection, it would certainly be nicer to silence them. And this is what we did.

[Andersson007]

Found several minor things to fix according to the Ansible documentation format (a few examples common for most the modules except the Latin phrase which is only in one):

no "notes" section, it should, at least, contain info about check_mode support
return object: line 1 does not start with a capital letter
return object: line 1 does not end with a dot
return object: no sample
description: line 2 does not end with a dot
opt command: abbreviations/latin phrases found 'via', use 'by/through' instead

Also ANSIBLE_METADATA block is no longer needed

[tadeboro]

We left the metadata block in on purpose because this is the only way we can communicate to the end-user on Ansible 2.9 that the content from the collection is certified. If we remove the metadata block, ansible-doc will classify content as community supported.

I will have a look at other issues now. That check mode is an annoying one since all our modules support check mode and adding notes just to state something that end-users expect feels a bit weird, but there is probably not much we can do about it.

[Andersson007]

ok, nice to here:)
Then wouldn't it be good to put something like "All the modules supports check_mode" somewhere, e.g. in the collection's README?
It could be important to know for newcomers, so the stocks of the collection will grow when they see it:)

[tadeboro]

We do have this information available, but not in the readme file because this is not where our users search for information (the Sensu Go collection is certified, and we do not expect our users to be developers or that they need to know anything about the development-side of Ansible collections). We have a documentation site available at https://sensu.github.io/sensu-go-ansible/, and the information about general module usage is at https://sensu.github.io/sensu-go-ansible/modules.html.

As for other issues found, I think I managed to address them all. I will release 1.7.1 later today or tomorrow.

[tadeboro]

Issues that the D&I working group identified in sensu.sensu_go's CoC (meeting link) and need to be resolved before this collection can become part of the ansible PyPI package:

1. CoC has no contact info (we need to copy the contact information from the canonical source at https://sensu.io/conduct).
2. Clarify the contributor's, maintainer's, and potential (online) participant's roles and responsibilities.
3. Add examples of (un)acceptable online behavior.

Things that would be nice to do but will not block the approval:

1. Add version or identifier to CoC.
2. Generalize CoC to use language that's slightly more project-oriented and less conference oriented.

@jillr Can you pitch in and correct me if I missed something important (I did my best to summarise the discussion from the meeting, but if history has taught me something is that I can mess things up in very innovative ways).

[tadeboro]

@cybette @mscherer Can you also pitch in? Thank you in advance.

[tadeboro]

I decided to act proactively and created sensu/sensu-go-ansible#248. I tried to address all of the points from the two list above, the only exception being the version identifier that I left out. I would rather wait with that one a bit since I hope I can get CoC updates for the Sensu Go Ansible Collections incorporated into Sensu's CoC and then attach a version to that.

[jillr]

Updated CoC looks good to me, thanks very much @tadeboro

[felixfontein]

The collection looks good! I have some small details that should be addressed, but these should be easily fixable.

General notes:

• Collection should mention somewhere that it does not support Python 2.6. Maybe mentioning that in notes or requirements in a doc fragment used by all modules would make sense? Then Ansible users will also see that on the Ansible docsite. (Minor refactorings and updates to modules and utilities sensu/sensu-go-ansible#249)
• plugins/modules/entity.py calls module.deprecate() without collection_name keyword! To support Ansible < 2.9.10, better use try/except so that Ansible 2.9.10+ users get a correct deprecation message. (Minor refactorings and updates to modules and utilities sensu/sensu-go-ansible#249)

Public availability and communication:

• published on Ansible Galaxy Ansible Galaxy with version 1.0.0 or later
• has a policy of releasing, versioning and deprecation announced to contributors and users in some way
  • Comment: I cannot find anything about that, neither in the collection repository, nor on the docs site (https://sensu.github.io/sensu-go-ansible/index.html). Fixed in Add release policy sensu/sensu-go-ansible#247
• have a Code of Conduct (CoC) compatible with the Ansible Code of Conduct (CoC)
  • CoC is present, compatibility with Ansible's is determined by Ansible's Diversity Working Group
• have a publicly available issue tracker that does not require a paid level of service to create an account or view issues

Standards and documentation:

• adheres to semantic versioning
• follows licensing rules
• follows the Ansible documentation standards and the style guide
  • Comment: uses I(...) and sometimes no formatting for environment variables (see auth.verify option for example, and namespace). That should better be C(...).
• follows development conventions
• has README.md
• documentation, examples, and return use FQCNs for M(..), examples, and seealso subsections
• modules (or plugins) from ansible-base use ansible.builtin. as a FQCN prefix
• documentation and return sections use version_added: containing the collection version for which an option, module or plugin was added
• FQCNs is used for extends_documentation_fragment:, unless you are referring to doc_fragments from ansible-base

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

Tests:

• passed ansible-test sanity
• if test/sanity/ignore*.txt exists, it does not contain error codes listed here
• has CI tests up and running against each of the "major versions" of ansible-base/ansible-core that the collection supports
  • Comment: sanity checks are not run for Python 2.6 (this is excused, but needs to be documented), Python 3.5 and Python 3.9!
  • Sanity checks should be run for all Python versions that are supported, i.e. here also for Python 3.5 and 3.9 (the latter is supported only by ansible-base 2.10+).
• all CI tests run against every pull request
• all CI tests run against a commit that releases the collection; if they don't pass, the collection won't be released
• all CI tests run regularly (nightly, or at least once per week)

[tadeboro]

Collection should mention somewhere that it does not support Python 2.6. Maybe mentioning that in notes or requirements in a doc fragment used by all modules would make sense? Then Ansible users will also see that on the Ansible docsite.

I extended the requirements section of each module with common requirements fragment since as you said, this way, requirements will be visible on docs.ansible.com. (sensu/sensu-go-ansible@b1890e6)

plugins/modules/entity.py calls module.deprecate() without collection_name keyword! To support Ansible < 2.9.10, better use try/except so that Ansible 2.9.10+ users get a correct deprecation message.

That makes sense, especially since I hope most users will eventually manage to update their installations to the recent-enough version of Ansible. Implementing this was not as easy as I was hoping, but things almost never are. (sensu/sensu-go-ansible@6ef9599)

has a policy of releasing, versioning and deprecation announced to contributors and users in some way

• Comment: I cannot find anything about that, neither in the collection repository, nor on the docs site (https://sensu.github.io/sensu-go-ansible/index.html).

I could have sworn that I wrote that document more than I year ago. And I was correct, but unfortunately, that document got stuck in one of my local branches and was never rendered. Thank you very much for noticing this omission. (sensu/sensu-go-ansible@943abcd)

have a Code of Conduct (CoC) compatible with the Ansible Code of Conduct (CoC)

• CoC is present, compatibility with Ansible's is determined by Ansible's Diversity Working Group

We are actively working on that issue in sensu/sensu-go-ansible#248 and #6 (comment)

[felixfontein]

@tadeboro thanks! I've ticked almost all boxes now. BTW, is there a reason that sanity tests are not run for Python 3.5 and 3.9? (I've ticked that box already, but maybe I shouldn't have to pull more attention to it...)

[tadeboro]

We do not test Python 3.5 to be at least somewhat eco-friendly since Python 3.5 is not supported anymore and none of the major distros offered to step-in as Red Hat did for Python 2.7 on RHEL 7 and 8.

Testing on Python 3.9 is not there yet because I am lazy ;) Adding 3.9 to our test suite is part of the small overhaul of our CI/CD pipeline that will replace the ansible package with either ansible-base or ansible-core (this will also allow us to start testing against the development branch). But maybe I should decouple the sanity test update and add that version to our sanity test matrix in a separate PR not to delay things any further.

[jillr]

Voted on CoC in D&I WG meeting today.
Including @mscherer's approval of changes in sensu/sensu-go-ansible#248; all were in favor (@tadeboro abstaining).
Approved.

[tadeboro]

@felixfontein sensu.sensu_go 1.7.2 with all suggestions from the review is ready at https://galaxy.ansible.com/sensu/sensu_go

[gundalow]

PR raised ansible-community/ansible-build-data#53 to add this to ansible

[dmsimard]

Approved by majority and merged !

Thanks everyone and great work @tadeboro :)