Add guidelines on variable naming

This captures some discussion over the scoping of variable names
during some recent role development.  It tries to provide some
guidelines to prefixing of global variable names in roles and
"module-like" roles.

Since "deprecation.rst" is now holding a few different things, it
makes more sense as "policy.rst".

Reorganise to be nested in one more level, and add a contents section
to help find sections easier.

Change-Id: I0d551eefd33744ffa23418d0780769a7e52fe9cf

doc/source/index.rst

@@ -4,7 +4,7 @@
    :maxdepth: 1
 
    install
-   deprecation
+   policy
    jobs
    roles
 

doc/source/policy.rst

@@ -1,5 +1,13 @@
+Policy
+======
+
+Below are some guidelines for developers contributing to `zuul-jobs`.
+
+.. contents::
+   :local:
+
 Deprecation Policy
-==================
+------------------
 
 Because `zuul-jobs` is intended for wide use by any Zuul, we try to
 take care when making backwards incompatible changes.
@@ -16,7 +24,7 @@ timeframe.  Otherwise, you may wish to temporarily switch to a local
 fork of `zuul-jobs` (or stop updating it if you already have).
 
 New Zuul Features
------------------
+*****************
 
 When a new feature is available in Zuul, the jobs in `zuul-jobs` may
 not be able to immediately take advantage of it.  We need to allow
@@ -26,14 +34,14 @@ after the first Zuul release with the required feature before merging
 a change to `zuul-jobs` which uses it.
 
 Deprecated Zuul Features
-------------------------
+************************
 
 Before deprecating a feature in Zuul which is used by `zuul-jobs`, the
 usage of the feature must be removed from `zuul-jobs` according to the
 deprecation policy described above.
 
 Python Version Policy
-=====================
+---------------------
 
 ``zuul-jobs`` targets Python 2.7 onwards and Python 3.5 onwards (note
 this differs slightly from Ansible upstream, where the policy is 2.6
@@ -44,6 +52,24 @@ Library code should be written to be compatible with both.  There are
 some tips on this in `Ansible and Python 3
 <https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__.
 
+Role Variable Naming Policy
+---------------------------
+
+Variables referenced by roles from global scope (often intended to be
+set via ``host_vars`` and ``group_vars``, but also set during role
+inclusion) must be namespaced by prepending their role-name to the
+variable.  Thus ``example-role`` would have variables with names such
+as ``example_role_variable``; e.g.
+
+.. code-block:: yaml
+
+  tasks:
+    - name: Call "example" role
+      include_role:
+        name: example-role
+      vars:
+        example_role_variable: 'something'
+
 .. _zuul-announce: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce
 .. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss