Unclear documentation requirements when importing a collection

[JGoutin]

Bug Report

SUMMARY

I get some errors when trying to import my collection to update it (it was successfully imported in the past).

Problems are related to the required documentation inside the collection.

I get following successive errors:

• Error Message: No role readme found.: Each role must have a file named <collection>/roles/<role_name>/README.md (case sensitive).
• Error Message: Could not find file readme.md: The collection must have a file name <collection>/readme.md (Case sensitive, and different to roles)
• Error Message: No collection readme found: I already have a <collection>/readme.md, but I also requires an extra <collection>/README.md.

The requirement of both <collection>/readme.md and <collection>/README.md looks like a bug. Readme files names may be case insensitive (Not only for the collection readme).

Error messages generally not help to find exactly what to do (It may give the exact path of awaited files).

The import may scan the whole collection and show all errors at once. Actually it stop on the first error, so the user requires to retry until success when there is multiples errors in its collection.

The documentation does not provides all required information:

• No mention on role documentation.
• No mention of what is mandatory or optional.

STEPS TO REPRODUCE

ansible-galaxy collection build --force && ansible-galaxy collection publish --api-key XXXXXXX *.tar.gz

I tested :

• Role readme file is <collection>/docs/<role_name>.md => Error Message: No role readme found.
• Role readme file is <collection>/roles/<role_name>/readme.md => Error Message: No role readme found.
• Role readme file is <collection>/roles/<role_name>/README.md => OK, for roles
• Collection readme is <collection>/readme.md. => Error Message: No collection readme found
• Collection readme is <collection>/README.md. => Error Message: Could not find file readme.md
• Collection readme is <collection>/readme.md + addition of an empty docs folder. => Error Message: No collection readme found
• Collection readme is <collection>/readme.md + addition of a non empty docs folder. => Error Message: No collection readme found
• Collection readme is both <collection>/readme.md and <collection>/README.md. => OK

EXPECTED RESULTS

Collection imported with success.

ACTUAL RESULTS

Collection import failure, see errors bellow.

[chouseknecht]

Think the importer pretty much follows the collections developer guide.

[JGoutin]

Concerning the collection developer guide:

I read this documentation and it says that the collection structure contains a README.md, that there is a docs directory for documentation, and that galaxy.yml is required.

There is no mention about the required README.md file in the roles directories. I may logically want to add it in the docs directory, with the rest of the documentation, or I may want to use a file named readme.md.

There is also nothing that the collection readme is required, it only says that galaxy.yml is required (And almost all the other content is optional).

The rest of the documentation is great, I know that writing an exhaustive documentation is hard. This is just a feedback.

[izgeri]

I just hit the error Galaxy import process failed: No role readme found. when importing a collection that was imported successfully in the past, but we added a role and didn't realize a role README was required.

I've looked through the developing collections docs and I can't see any requirement stated there that the roles/ directory have a README file - I'm not even sure what the purpose of that file is, since I have my role information in the README in the collection project root directory.

Can you please advise on what is expected in this role README file, and where I can find more information about this requirement? Thanks :)

[voidengineer]

I think those errors should also be reported by ansible-galaxy collection build or even ansible-lint.
Then I would have seen this a long time before trying to publish my first own collection.

[nodiscc]

In my case ansible-galaxy collection publish started failing with No role readme found (it was previously working):

$ ansible-galaxy collection publish --token "$ANSIBLE_GALAXY_PRIVATE_TOKEN" nodiscc-xsrv-1.5.0.tar.gz
Publishing collection artifact 'path/to/xsrv.git/nodiscc-xsrv-1.5.0.tar.gz' to default https://galaxy.ansible.com/api/
Collection has been published to the Galaxy server default https://galaxy.ansible.com/api/
Waiting until Galaxy import task https://galaxy.ansible.com/api/v2/collection-imports/17589/ has completed
ERROR! Galaxy import process failed: No role readme found. (Code: None)

The log on https://galaxy.ansible.com/my-imports/18005 says:

Starting import: task_id=17589, artifact_id=17591 
Importing with galaxy-importer 0.4.0 
Getting doc strings via ansible-doc 
Finding content inside collection 
Loading role roles 
Could not get role description, no role metadata found 
Import Task "17589" failed: No role readme found. 

I worked around it by creating the file:

$ touch roles/README.md
$ ansible-galaxy collection publish --token "$ANSIBLE_GALAXY_PRIVATE_TOKEN" nodiscc-xsrv-1.5.0.tar.gz
# import OK

I can't see any requirement stated there that the roles/ directory have a README file - I'm not even sure what the purpose of that file is, since I have my role information in the README in the collection project root directory.

Same. I think that requiring a roles/README.md is simply a bug that was added somewhere between ansible 4.9.0 and 5.2.0 (https://gitlab.com/nodiscc/xsrv/-/compare/1.4.0...1.5.0?from_project_id=14306200#836efb6e25a091dcb4ff8e1dbb2f0be6a5cbf14c_22_22)

[mkayontour]

Any Updates on this Topic? Will be the REDME for every role a requirement in the future? Or is it a temporary issue still?

[nodiscc]

I can still reproduce this

$ ansible-galaxy --version
ansible-galaxy [core 2.12.7]

touch roles/README.md reliably works around the problem, but there is no good reason to require a readme file in the roles/ directory in the first place...

[nodiscc]

Bug is still present in ansible-core 2.14.1

Additionally the collection's Content tab appears empty on https://galaxy.ansible.com/nodiscc/xsrv (only shows a single role named roles)

[enmanuelmoreira]

I have the same issue and I fix it by including the main.yml file inside a new folder called "meta" on each role which is part of the collection, with some information about the role:

dependencies: []
galaxy_info:
  author: enmanuelmoreira
  role_name: proxmox_lxc
  description: Configuring proxmox lxc role.
  license: license (MIT)
  min_ansible_version: 2.7
  platforms:
    - name: Ubuntu
      versions:
        - 20.04
        - 22.04
    - name: Debian
      versions:
        - 11

[nodiscc]

including the main.yml file inside a new folder called "meta" on each role

This doesn't fix the problem for me, I always had a meta/main.yml file for each role (https://github.com/nodiscc/xsrv/tree/master/roles), but the problem is still present.

[nodiscc]

Now the workaround I mentioned earlier doesn't even work anymore:

$ for i in roles/*; do ls $i/README.md; done
roles/apache/README.md
roles/backup/README.md
roles/common/README.md
roles/dnsmasq/README.md
roles/docker/README.md
roles/gitea/README.md
roles/gotty/README.md
roles/graylog/README.md
roles/handlers/README.md
roles/homepage/README.md
roles/jellyfin/README.md
roles/jitsi/README.md
roles/libvirt/README.md
roles/mail_dovecot/README.md
roles/matrix/README.md
roles/monitoring/README.md
roles/monitoring_goaccess/README.md
roles/monitoring_netdata/README.md
roles/monitoring_rsyslog/README.md
roles/monitoring_utils/README.md
roles/mumble/README.md
roles/nextcloud/README.md
roles/openldap/README.md
roles/postgresql/README.md
roles/readme_gen/README.md
roles/samba/README.md
roles/shaarli/README.md
roles/transmission/README.md
roles/tt_rss/README.md
roles/wireguard/README.md

$ touch roles/README.md
$ ansible-galaxy collection build --force
Created collection for nodiscc.xsrv at /home/live/GIT/xsrv.git/nodiscc-xsrv-1.17.0.tar.gz
$ ansible-galaxy collection publish --token "$ANSIBLE_GALAXY_PRIVATE_TOKEN" nodiscc-xsrv-1.17.0.tar.gz
Publishing collection artifact '/home/live/GIT/xsrv.git/nodiscc-xsrv-1.17.0.tar.gz' to default https://galaxy.ansible.com/api/
Collection has been published to the Galaxy server default https://galaxy.ansible.com/api/
Waiting until Galaxy import task https://galaxy.ansible.com/api/v2/collection-imports/31633/ has completed
[WARNING]: Galaxy import warning message: Could not get role description, no role metadata found
 [ERROR]: Galaxy import error message: Import Task "31633" failed: No role readme found.
ERROR! Galaxy import process failed: No role readme found. (Code: None)

ansible 8.4.0 (ansible-core 2.15.4)