search

ansible / ansible-documentation

Ansible community documentation
https://docs.ansible.com/
GNU General Public License v3.0
83 stars 495 forks source link

Improve meta/main.yml documentation for roles #1241

Open samccann opened 7 months ago

samccann commented 7 months ago

We mention the role structure and some specific portions of meta/main.yml in https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#using-meta-main-yml but we don't define the whole thing anywhere in docs.

The specifc trigger for this issue is a user getting an ansible-lint error of : meta-no-info: Role info should contain platforms

...and had no way to find out what this platforms section is about. In general, would be good to have a well-defined example of this in the docs.

Perhaps an extension of https://github.com/ansible/ansible/blob/devel/lib/ansible/galaxy/data/apb/meta/main.yml.j2

samccann commented 7 months ago

This forum topic may have some helpful information as well - https://forum.ansible.com/t/role-meta-data-platform-key-broken/4651

It mentions an old galaxy api page which can be reached at https://old-galaxy.ansible.com/api/v1/platforms/

samccann commented 7 months ago

...continuing the linkfest of places that might have the details needed - https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/schemas/meta.json

samccann commented 7 months ago

Discussed in DaWGs meeting: In general, ansible-lint is specific to Galaxy and may not be the definitive list we want to use in the general ansible docs.

s-hertel commented 7 months ago

I removed the platforms: blocks from the ansible-core role templates, since the URL documenting the choices is no longer there.

Not sure if this has been discussed elsewhere, but the related forum post appears to be about roles in collections, not standalone roles, and I'm not sure Galaxy and ansible-lint are in alignment on that (beyond Galaxy calling ansible-lint). I don't think a role in a collection can set a custom namespace or role_name in the galaxy_info of a role it contains for example, but a standalone role can change how it's imported in Galaxy by setting those fields. Maybe it's worth mentioning that caveat for collections in https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#using-meta-main-yml, since all the templates contain galaxy_info because they were created for standalone roles.

I did find a very brief mention of the meta/main.yml here https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/community/userguide/#changing-the-role-name (pretty sure it's role_name though).