Installation docs don't include pre-requisites.

[coverprice]

Bug Summary

Repro steps:

1. Create a new local venv and install ansible-core.
2. Follow the instructions in this repo's README to install this collection, i.e. ansible-galaxy collection install ansible.platform

Expected behavior: The collection installs.

Actual behavior: An obtuse error message, with a (misleading) hint about using --pre:

[ERROR]: Failed to resolve the requested dependencies map. Could not satisfy the following requirements:
* ansible.platform:* (direct request)
Hint: Pre-releases hosted on Galaxy or Automation Hub are not installed by default unless a specific version is requested. To enable pre-releases globally, use --pre: [RequirementInformation(requirement=<ansible.platform:* of type 'galaxy' from Galaxy>, parent=None)]: Requirements conflict: <ansible.platform:* of type 'galaxy' from Galaxy>

Cause: ansible.platform is hosted on Automation Hub, not Galaxy, but a default Ansible install is not configured to use Automation Hub. Thus, the install command in a default environment couldn't find the collection.

Root Cause: The installation instructions do not specify that ansible-galaxy must be configured to use Automation Hub for the installation command to succeed. (This also applies to many other ansible namespace packages, and infra.aap_configuration.)

Impact: This simple documentation omission, combined with the misleading error message, caused significant delays to discover the cause and create a solution. This probably cost us at least a couple of days.

Suggested fix: For this collection and other ansible collections, add to the "Requirements" section that the collections are hosted on Automation Hub, and so ansible-galaxy must be configured to use Automation Hub as a collection source.

(For ansible-galaxy, I will make a separate issue to suggest that the error message is clearer: that the collection was simply not present on the server it queried, rather than the more obtuse "Could not satisfy the following requirements" which strongly implied a problem with specifying the version, not that the collection fundamentally didn't exist there)

To get ahead of any rebuttal that "AAP admins must use Automation Hub, so configuring ansible-galaxy to use Automation Hub should be obvious", I'd respond that my team are AAP users, not admins, who want to install this automation to manage our AAP configs using infra-as-code, and so it was not obvious to us that we would also need to belong to Automation Hub to use this.

Select the relevant components

• Proxy
• API
• Other