search

ansible / galaxy

Legacy Galaxy still available as read-only on https://old-galaxy.ansible.com - looking for the new galaxy -> https://github.com/ansible/galaxy_ng
Apache License 2.0
854 stars 328 forks source link

Unclear documentation requirements when importing a collection #2438

Open JGoutin opened 4 years ago

JGoutin commented 4 years ago

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:

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:

STEPS TO REPRODUCE

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

I tested :

EXPECTED RESULTS

Collection imported with success.

ACTUAL RESULTS

Collection import failure, see errors bellow.

chouseknecht commented 4 years ago

Think the importer pretty much follows the collections developer guide.

JGoutin commented 4 years ago

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 commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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)