Template of a short checklist to put into discussions about including new collections in Ansible

[Andersson007]

SUMMARY

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

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
• 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

Standards and documentation:

• adheres to semantic versioning
• follows licensing rules
• follows the Ansible documentation standards and the style guide
• 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
• 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)

Removed from the list (if anybody disagrees, please tell us):

• has maintainers subscribed on Changes impacting Collections and The Bullhorn
• has main as the default branch
• repository protection: disallowed merge commits
• branch protection: require linear history; include administrators
• has wiki pages and pinboards for corresponding working groups if exist
• has changelog related standards / mechanisms working and described somewhere

[Andersson007]

cc @gundalow @felixfontein @abadger @dericcrago @dmsimard
I'd like to put this (after your review) in https://github.com/ansible-collections/ansible-inclusion/discussions/

[dmsimard]

Thanks for picking this up!

use the Ansible Code of Conduct (CoC) by copying CODE_OF_CONDUCT.md into the root of your Git repository

Wording has changed but hasn't been merged yet: #136

has maintainers subscribed on Changes impacting Collections and The Bullhorn

Nice to have and should be encouraged but I'm not sure if it should be a requirement -- requiring it implies we have the ability to validate that the requirement is met and that means poking at the bullhorn subscriber list

 has main as the default branch
repository protection: disallowed merge commits
branch protection: require linear history; include administrators

My understanding is that those were guidelines for community collections but not necessarily requirements for inclusion in the Ansible package. Do we want to require them ?

[tadeboro]

Repository and collection management:
* [ ] has main as the default branch
* [ ] repository protection: disallowed merge commits
* [ ] branch protection: require linear history; include administrators

Not sure if these three points should be forced on 3rd-party repositories. These rules are OK for things hosted in the ansible-collections GitHub organization, but others might have different development preferences.

Edit: I see @dmsimard raised the same concerns, but only after I replied. Leaving my comment there as proof that I still do stupid things all the time ;)

[Andersson007]

@dmsimard @tadeboro thanks! i put all that i found in the requirements to discuss and leave or drop officially.
I moved the points you mentioned to a new section called Removed from the list, so others will see them.
The main goal now is to put the list in the discussions ASAP so that the collection maintainers can start working on fixing inconsistencies.

@gundalow @felixfontein @abadger we need your feedback as well.

[Andersson007]

@dmsimard i saw you merged #136 , changed the corresponding point a little bit

[felixfontein]

I also think the branch requirements are only for collections hosted in https://github.com/ansible-collections/, and I agree that this isn't formulated good :) I'll create a PR to improve the requirements page with this regard.

[felixfontein]

1. published on Ansible Galaxy

   should be changed to:

   published on Ansible Galaxy with version 1.0.0 or later

   We want stable releases.

2. if test/sanity/ignore*.txt exists, it does not contain validation listed here

   Instead of "validation", do you mean "error code" or "violation"?

3. has wiki pages and pinboards for corresponding working groups if exist

   I think this is not really something we require (and want to enforce).

[gundalow]

Repository and collection management:

• has main as the default branch
• repository protection: disallowed merge commits
• branch protection: require linear history; include administrators

Not sure if these three points should be forced on 3rd-party repositories. These rules are OK for things hosted in the ansible-collections GitHub organization, but others might have different development preferences.

Edit: I see @dmsimard raised the same concerns, but only after I replied. Leaving my comment there as proof that I still do stupid things all the time ;)

@tadeboro correct, these points are MUST for gh/ansible-collections and suggestions for others.

[Andersson007]

1. published on Ansible Galaxy

   should be changed to:

   published on Ansible Galaxy with version 1.0.0 or later

   We want stable releases.

2. if test/sanity/ignore*.txt exists, it does not contain validation listed here

   Instead of "validation", do you mean "error code" or "violation"?

3. has wiki pages and pinboards for corresponding working groups if exist

   I think this is not really something we require (and want to enforce).

@felixfontein changed, thanks!

[Andersson007]

Thanks everybody!
The inclusion window will close very soon.. So should we wait others or we could put it as is now (and maybe correct something later) to the open discussions to allow maintainers to start changing their collections to comply with the check list?
Maybe somebody would like to do it during the long holidays.
What do you think?

[felixfontein]

has changelog related standards / mechanisms working and described in wiki

We don't require this to be documented in the Wiki.

[Andersson007]

has changelog related standards / mechanisms working and described in wiki

We don't require this to be documented in the Wiki.

changed to described somewhere or should i remove this entirely? but how contributors will know about it?

[felixfontein]

We don't cover that in the requirements list. I guess contributors can be informed in every PR if needed.

What we definitely need in the checklist is the point "[ ] - Has changelog, preferably with changelogs/changelog.yaml".

[Andersson007]

We don't cover that in the requirements list. I guess contributors can be informed in every PR if needed.

What we definitely need in the checklist is the point "[ ] - Has changelog, preferably with changelogs/changelog.yaml".

persuaded:) Added

[felixfontein]

The checklist is now part of the repository: https://github.com/ansible-collections/overview/blob/main/collection_checklist.md

@Andersson007 thanks for all your work on this!

[Andersson007]

Thanks everyone!