Files identified in the description:
None

If these files are inaccurate, please update the component name section of the description or use the !component bot command.

click here for bot help

This comment will be updated as we decide on the overall structure of the README.md file. Please note it must be .md not .rst.

Collection Title

-- Add CI and code coverage badges. Sample included below:

-- Describe the collection and why a user would want to use it. What does the collection do?

Tested with Ansible

-- List which versions of Ansible this has been tested with. Must match what is in galaxy.yml.

Requirements

-- List any external requirements that the collection depends on. This should not be the collections that would be auto-installed, but other requirements, such as a minimum version of an OS etc.

Supported connections

--An optional section for network/cloud etc collections that support only specific connection types (such as HTTPAPI, netconf, etc).

Included content

-- Galaxy will eventually list the module docs within the UI, but until that is ready, you may need to either describe your plugins etc here, or point to an external docsite to cover that information.

Using the collection

-- Include some quick examples that cover the most common use cases for your collection content.

• https://docs.ansible.com/ansible/latest/user_guide/collections_using.html

Contributing to the collection

-- _Describe how the community can contribute to your collection. At a minimum, include how and where to create issues so users can report problems or enhancement requests for the collection. You should also list any requirements/recommended workflow, and testing you want for a smooth merge experience of community PRs. If you are following general Ansible contributor guidelines, you can link to - https://docs.ansible.com/ansible/latest/community/index.html
. _

Release Notes

-- Add a link to a changelog.md file or an external docsite to cover this information.

Roadmap

-- an optional section to include the roadmap for this collection, and the proposed release/versioning strategy so users can anticipate the upgrade/update cycle.

More information

-- List out where the user can find additional information, such as working group meeting times, slack/IRC channels, a documentation site for a product this collection works with, etc. The following links should be included:

• https://github.com/ansible-collections/overview
• https://docs.ansible.com/ansible/latest/user_guide/index.html
• https://docs.ansible.com/ansible/latest/dev_guide/index.html
• https://docs.ansible.com/ansible/latest/community/code_of_conduct.html

Licensing

--_ Include the appropriate license information here and a pointer to the full licensing details. See the GNU license example below._

GNU General Public License v3.0 or later

See LICENCE to see the full text.

Some example readme files:

• https://github.com/ansible-collections/kubernetes/blob/master/README.md

• https://github.com/ansible-collections/ibm_zos_core/blob/dev/README.md

Note - Galaxy currently uses a conservative markdown as follows:

Tags suitable for rendering markdown

markdown_tags = [
"h1", "h2", "h3", "h4", "h5", "h6",
"b", "i", "strong", "em", "tt",
"p", "br",
"span", "div", "blockquote", "code", "hr",
"ul", "ol", "li", "dd", "dt",
"img",
"a",
"sub", "sup",
]
and
tags=markdown_tags + ['pre', 'table', 'thead', 'th', 'tr', 'td']

A couple of thoughts

• Having a common set of badges would be cool, currently for the Windows ones we have the Shippable badge for CI status and Codecov.io for coverage info
• Do we know when docs.ansible.com will contain the docs for a collection to point the README to? I don't particularly want to document each plugin manually in a collection if the site is live, especially for collections with lots of plugins
• Release Notes should just be a link to the changelog/release notes and not all in the 1 README.md

Some of this stuff are best to be documented in separate files, have we settled down on the functionality of the docs folder in a collection?

I'd vote for a standalone "Tested with Ansible versions" section, which should already be in metadata?

@jborean93 - codecov.io looks to be used for a number of collections so that seems common already and I'll add to the template above. For CI status, we have a two types - Kubernetes uses github action, windows uses shippable. Do we need to find common ground there? (@geerlingguy ) or do we just want to suggest a CI badge should be added in general?

• module docs on docs.ansible.com - we likely won't have that available when collections go live is my guess. Things were sort of working, but were 'release independent'. Instructions on this changed about a week ago that said a couple of things - that we need to have release versions, and that those versions have to match ACD (which I don't know the timeframe on its availability vs collection release). So that leaves us in some trouble in this area. It's a moving space for sure, but I wanted something in the readme discussion at least to see what our backup options are if we don't have module docs on docs.ansible.com in time.

• I like the release notes in a separate file idea. I think one of the collections (maybe kubernetes?) is already doing this.

• the docs folder - still TBD. There was a plan at one point where Galaxy/AH would display whatever was in that file, but I don't think we'd have control over the order in the display (other than alphabetical I guess?). But that is one option for sure. Given that it won't be displayed in the UI, I wonder if users would find it? I guess the readme could have a github link to it until such time as it shows up 'someplace better'. It will also get just that much more complicated by the above ACD decision - which I would interpret to mean we would need a release note/ change log that covers all collections in a given ACD version, for all changes to each collection that happened between ACD versions. (aka changelog fragments vs one file).

For CI status, we have a two types - Kubernetes uses github action, windows uses shippable

For generic collections then it could really be anything, even Travis-CI or Azure DevOps Pipelines as it's up to the author of the collection to decide. A few of the migrated collections will continue to use Shippable because that's what ansible-test is designed for and is required for things like spinning up Windows hosts in AWS using the same mechanism as the CI in ansible/ansible.

Okay I've added the comments thus far to the README.md template comment.

For users just getting started with a collection with the intent to debug or contribute, should we point to a "running from source" doc, that shows the clone of the collection and 1) a link to their .ansible folder 2) playbook ajacent or 3) and entry in an ansible.cfg file? I suspect we may already have this somewhere but as a link in each collection it may be useful rather than each collection owner reinventing the wheel

Can we leverage the Ansible code of conduct for each collection moving forward? (link to it) https://docs.ansible.com/ansible/latest/community/code_of_conduct.html#community-code-of-conduct

Some of this may be applicable, and need to be updated as well https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_checklist.html

For collection that have a documented release and versioning strategy, we should include a section for this. Version and release guidelines are WIP for a number of collections...

Also, I was wondering whether it'd make sense to at least add a 'default suggested license', such Apache2.0 or GPLv3 to the template. I guess we can assume if people doesn't want to use it they'd just remove it and I'd rather have that than no license ;)

Specific to networking collections and even if it'd be on the metadata, it might be worth adding something akin to 'tested with {network_os} {network_os_version}

how about a section for supported connection methods?

Is supported connection something that extends beyond network collections?

Is supported connection something that extends beyond network collections?

Yes, HTTPAPI is something that can be used beyond network. Also, local as well. WinRM for Windows, etc.

https://docs.ansible.com/ansible/latest/plugins/connection.html

I don’t see how supported connection methods really is a thing outside of networking. For Windows you can use any connection plugin that works with Windows regardless of the module.

To @jborean93's point, none of the collections I work on care much about supported connection methods (most use SSH, local, or docker but it doesn't affect much real-world use or expectations.

I think the README's should have an ideal / recommended structure, but any individual collection may choose to diverge as needed (e.g. networking collections might want to add a section on supported connection methods).

In Galaxy for roles, roles get a default README but a lot of people change them a bit to suit their needs. I think the same thing can/should happen for collections. The only major difference is I know some collections will make their way to Automation Hub and be more strictly maintained, where more uniformity might be desirable.

Approximately a third of all modules in 2.9 are network related, and connection methods will become more important with the various means to do so (local, network_cli, httpapi, netconf, grpc tbd, etc). If it isn't applicable for others that's fine but it's a big piece for network and a few others.

+1 to that, @abenokraitis , that's something I'm frequently asked over the irc.

Okay I've added the comments to date to the template. @gundalow, @abenokraitis @jborean93 @geerlingguy @cidrblock @danielmellado please take another look before we finalize this! Thanks!

Thanks for doing this, it looks really good.

1. Collections will generally uses GitHub Actions or Shippable.

2. If code coverage is used it will generall be Codecov.io

3. Contributing to the collection If you allow community contributions to your collection
   Could we please rephrase this so that contributions are default.

Can we leverage the Ansible code of conduct for each collection moving forward? (link to it) https://docs.ansible.com/ansible/latest/community/code_of_conduct.html#community-code-of-conduct

The Code of Conduct exists in the special .github repo so it's automagically linked in all repos under github.com/ansible-collections, etc https://github.com/ansible-collections/kubernetes/community We can (should?) link to the CoC from each README as well.

5. License wise I think GPLv3+

6. GitHub has a "new" concept of a Template repo, which is a special repo which you can easily copy to a new repo. I've created one here https://github.com/ansible-collections/collection_template
   I think this is where we should put the default README. We can also put the basic GitHub Action workflow files here as well.
   This means rather than documenting how to set things up from scratch we use this repo as the source of truth and keep it updated.

LGTM

PR now exists for this at ansible-collections/collection_template#1