Skip to content
This repository has been archived by the owner on Apr 10, 2021. It is now read-only.

Add initial documentation conventions #17

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add initial documentation conventions #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,21 @@ and [development](https://docs.ansible.com/ansible/latest/dev_guide/index.html).
`foo_packages`, and the extra packages should be passed in a variable named `foo_extra_packages`,
which should default to an empty array in `defaults/main.yml` and be documented as such.

## Documentation conventions

* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@richm richm Apr 15, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...

* Use fully qualified role names in examples, like: `linux-system-roles.$ROLENAME` (with
the Galaxy prefix).
* Use RFC [5737](https://tools.ietf.org/html/rfc5737),
[7042](https://tools.ietf.org/html/rfc7042#section-2.1.1) and
[3849](https://tools.ietf.org/html/rfc3849) addresses in examples.
* Modules should have complete metadata, documentation, example and return blocks as
described in the
[Ansible docs](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html).

References
==========

Expand Down