Add a guide page that explains various mechanisms for developing a collection

[sivel]

There have been numerous times where users have attempted to git clone a repo, cd into it, and attempt running ansible-playbook playbooks/some_playbook.yml to test a collection. In this manner ansible-core has no context that the playbook is in a collection, nor will changes be made to core to support any attempted magic at doing so.

This may be related to lack of documentation about common ways to develop collections, so we should expand on this further.

My typical approach generally revolves around isolation.

1. Create a project directory

2. inside that project directory create a collections directory

3. git clone or init a collection repo into the proper directory structure of collections/<namespace>/<name>

4. Develop content in the project directory to manually develop the collection, this may involve creating a playbook like runme.yml which does something like which can be executed:

   import_playbook: <namespace>.<name>.<playbook_name>
   

Other mechanisms, such as that documented for ansible-dev-environment may be useful for the guide as well.

I'm sure others may have ideas, but I generally recommend not using global collection dirs, nor using ansible-galaxy collection install git+..., and instead just directly interacting with git and proper directory structures that ansible-core supports.

[sivel]

cc @cidrblock

[acozine]

We currently have https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_creating.html - should we expand that documentation, or create something new, or both?

[sivel]

I'd be fine with extending that. As of now it leaves a lot to the reader.

[samccann]

@Andersson007 just Fyi ^^

[Andersson007]

Should we maybe ask the community to help here? via Bullhorn / community-wg post ? Speaking about ansible-dev-env, etc. i would mention it in seealso maybe but would limit the guide itself with only essential things like git and tools provided by ansible-core.