Add initial documentation conventions #17
Conversation
|
If people have several example playbooks, they might want to have a directory to place them into to have more clear structure. Instead of getting lots of differently named folder names, I would suggest to use the |
| * Example playbooks are to live in the root directory, not in a separate subdirectory, and | ||
| prefixed with `example-` . Rationale: Ansible depends on particular structure, where | ||
| directory names have special meanings. If one introduces a new directory, anybody else | ||
| who looks at the code wonders whether it also has some special meaning. |
There was a problem hiding this comment.
Collections have both a docs/ and a playbooks/ sub-directory: https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-structure
Why can't we use those in our role structure? Will it cause problems with ansible galaxy if the role on github has a non-standard directory? Will it cause problems with RPM packaging or using roles from an RPM package?
Or do we need a sub-directory hey-this-is-non-standard-stuff/ with docs/ and playbooks/ (and whatever else we want)?
There was a problem hiding this comment.
Inside of a role, there's no restriction on extra folders. I agree we should put them under a folder, and following the convention of a playbooks/ dir from Collections makes the most sense to me.
Alternatively, if you have a sample playbook, why not just make it into a Molecule scenario so we get testing around it? That's where I always look for sample playbooks in my own roles.
There was a problem hiding this comment.
Then I suggest we change the standard to say something like this:
Example playbooks can live in the root directory, and will be prefixed with "example-". If there are many such playbooks that clutter the root directory, the directory "playbooks/" can be used for these playbooks. Rationale: Although there is no standard "playbooks/" directory for Ansible Roles, there is a need to organize playbooks in a separate folder, if there are many such playbooks (where "many" is in the judgement of the role maintainer). Ansible Collections defines a "playbooks/" sub-directory for Collections - https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-structure - Use this for Roles in the absence of any Roles specific standard for this.
There was a problem hiding this comment.
Well, this was proposed by @robled and the text summarizes the reasoning that led to it. We heard no objection at that time.
Concerning docs/ and playbooks/ in collections, which one is supposed to be used for examples then? The documentation does not even say that.
Alternatively, if you have a sample playbook, why not just make it into a Molecule scenario so we get testing around it? That's where I always look for sample playbooks in my own roles.
- we are not using Molecule scenarios heavily
- that's not a place where a user would look for examples
- examples are often not suitable as tests - for example, they can contain invalid addresses, see "Use RFC 5737, 7042 and 3849 addresses in examples." in this very PR, and there will likely be other incompatibilities.
If an example is suitable as a test, we have a symlink in tests/ to it, which makes it usable both as an example and as a test.
There was a problem hiding this comment.
Good points have been made by the group with regards to this, and my previous opinion on this has changed. Given that Collections has given us some official guidance on other directories we can create that are becoming standard, I am in support of whatever Collections suggests, including docs/, playbooks/, etc...
| * Example playbooks are to live in the root directory, not in a separate subdirectory, and | ||
| prefixed with `example-` . Rationale: Ansible depends on particular structure, where | ||
| directory names have special meanings. If one introduces a new directory, anybody else | ||
| who looks at the code wonders whether it also has some special meaning. |
There was a problem hiding this comment.
Inside of a role, there's no restriction on extra folders. I agree we should put them under a folder, and following the convention of a playbooks/ dir from Collections makes the most sense to me.
Alternatively, if you have a sample playbook, why not just make it into a Molecule scenario so we get testing around it? That's where I always look for sample playbooks in my own roles.
This is the same change as in PR oasis-roles#17 minus the controversial part.
|
What do we want to do with this PR? |
First of all, I would like to have the uncontroversial subset in #20 merged. |
@t-woerner