[Docs] Describe variable files locations

Our best practices don't include variable files locations.
This should fix it.

Change-Id: Ic80afad76b425ec46e6ffb04d9de795ee71184e8

doc/source/developer-docs/additional-roles.rst

@@ -7,7 +7,7 @@ or infrastructure service, or to improve an existing role, the
 OpenStack-Ansible project would welcome that contribution and your assistance
 in maintaining it.
 
-Recommended procedure to develop a Role
+Recommended procedure to develop a role
 ---------------------------------------
 
 #. Deploy OpenStack-Ansible (possibly using
@@ -22,36 +22,10 @@ Recommended procedure to develop a Role
 
 .. _an AIO: quickstart-aio.html
 
-Writing a new Role
+Writing a new role
 ------------------
-Most OpenStack services will follow a common series of stages to install or
-update a service deployment. This is apparent when you review `tasks/main.yml`
-for existing roles.
 
-#. pre-install: prepare the service user group and filesystem directory paths
+Here are the steps to write the role:
-   on the host or container
-#. install: install system packages, prepare the (optional) service virtual
-   environment, install service and requirements (into a virtual environment)
-#. post-install: apply all configuration files
-#. messaging and db setup: db user and database prepared, message queue vhost
-   and user prepared
-#. service add: register the service (each of: service type, service project,
-   service user, and endpoints) within Keystone's service catalog.
-#. service setup: install a service-startup script (init, upstart, SystemD,
-   etc.) so that the service will start up when the container or host next
-   starts.
-#. service init/startup: signal to the host or container to start the services
-
-There may be other specialized steps required by some services but most of the
-roles will perform all of these at a minimum. Begin by reviewing a role for a
-service that has something in common with your service and think about how you
-can fit most of the common service setup and configuration steps into that
-model.
-
-.. HINT:: Following the patterns you find in other roles can help ensure your role
-   is easier to use and maintain.
-
-Steps to writing the role:
 
 #. You can review roles which may be currently in development by checking our
    `specs repository`_ and `unmerged specs`_ on review.openstack.org. If you
@@ -69,6 +43,7 @@ Steps to writing the role:
 #. Generate a meta/main.yml right away. This file is important to Ansible to
    ensure your dependent roles are installed and available and provides others
    with the information they will need to understand the purpose of your role.
+
 #. Develop task files for each of the install stages in turn, creating any
    handlers and templates as needed. Ensure that you notify handlers after any
    task which impacts the way the service would run (such as configuration
@@ -79,13 +54,50 @@ Steps to writing the role:
       discover a need for them. You can also develop documentation for your
       role at the same time.
 
+#. Add tests to the role.
+#. Ensuring the role deploys with an AIO.
+
+Writing tasks in a role
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Most OpenStack services will follow a common series of stages to install or
+update a service deployment. This is apparent when you review `tasks/main.yml`
+for existing roles.
+
+#. pre-install: prepare the service user group and filesystem directory paths
+   on the host or container
+#. install: install system packages, prepare the (optional) service virtual
+   environment, install service and requirements (into a virtual environment)
+#. post-install: apply all configuration files
+#. service add: register the service (each of: service type, service project,
+   service user, and endpoints) within Keystone's service catalog.
+#. service setup: install a service-startup script (init, upstart, systemd,
+   etc.) so that the service will start up when the container or host next
+   starts.
+#. service init/startup: signal to the host or container to start the services,
+   make sure the service runs on boot.
+
+There may be other specialized steps required by some services but most of the
+roles will perform all of these at a minimum. Begin by reviewing a role for a
+service that has something in common with your service and think about how you
+can fit most of the common service setup and configuration steps into that
+model.
+
+.. HINT:: Following the patterns you find in other roles can help ensure your role
+   is easier to use and maintain.
+
 .. _(see also the spec template): https://git.openstack.org/cgit/openstack/openstack-ansible-specs/tree/specs/templates/template.rst
 .. _specs repository: https://git.openstack.org/cgit/openstack/openstack-ansible-specs
 .. _unmerged specs: https://review.openstack.org/#/q/status:+open+project:openstack/openstack-ansible-specs
 .. _Best Practice: https://docs.ansible.com/ansible/playbooks_best_practices.html#directory-layout
 
-Adding tests to a Role
+Keep in mind a role candidate for inclusion should respect our
-----------------------
+`Ansible Style Guide`_.
+
+.. _Ansible Style Guide: contribute.html#ansible-style-guide
+
+Adding tests to a role
+^^^^^^^^^^^^^^^^^^^^^^
 
 Each of the role tests is in its tests/ folder.
 
@@ -110,9 +122,9 @@ This folder contains at least the following files:
 
 .. _tests repository: https://git.openstack.org/cgit/openstack/openstack-ansible-tests
 
+Deploying the role
+^^^^^^^^^^^^^^^^^^
 
-Deploying the Role
-------------------
 #. Include your role on the deploy host. See also `Adding Galaxy roles`_.
 #. Perform any other host preparation (such as the tasks performed by the
    ``bootstrap-aio.yml`` playbook). This includes any preparation tasks that

doc/source/developer-docs/contribute.rst

@@ -314,6 +314,35 @@ The following convention is used:
 
 * A tag including the word ``upgrade`` handles all the upgrade tasks.
 
+Variable files conventions
+--------------------------
+
+The variables files in a role are split in 3 locations:
+
+#. The `defaults/main.yml` file
+#. The `vars/main.yml` file
+#. The `vars/<platform specific>.yml` file
+
+The variables with lower priority should be in the `defaults/main.yml`.
+This allows their overriding with group variables or host variables.
+A good example for this are default database connection details, default
+queues connection details, or debug mode.
+
+In other words, `defaults/main.yml` contains variables that are meant to
+be overridable by a deployer or a continuous integration system.
+These variables should be limited as much as possible, to avoid
+increasing the test matrix.
+
+The `vars/main.yml` is always included. It contains generic
+variables that aren't meant to be changed by a deployer. This includes
+for example static information that aren't distribution specific (like
+aggregation of role internal variables for example).
+
+The `vars/<platform specific>.yml` is the place where distribution
+specific content will be stored. For example, this file will hold
+the package names, repositories urls and keys, file paths, service
+names/init scripts.
+
 Development cycle checklist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~