docs: explain where to define variables for use in roles

Signed-off-by: Andrew Schoen <aschoen@redhat.com>

diff --git a/README.rst b/README.rst
index dff38bc671dc300cbcf211cd38629b0c6f74c70a..acf02f441a8a7e6502e7d243c8f8fa6abaff0c12 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -44,6 +44,26 @@ if you prefer.
 **NOTE:** Some playbooks require specific groups to be defined in your inventory. Please refer to
 ``hosts`` in the playbook you want to use to ensure you've got the proper groups defined.
 
+Where should I put variables?
+-----------------------------
+
+All variables should be defined in ``defaults/main.yml`` for the role they're primarily used in.
+If the variable you're adding can be used in multiple roles define it in ``defaults/main.yml``
+for both roles. If the variable can contain a reasonable default value that should work for all
+possible labs then define that value in ``defaults/main.yml`` as well.  If not, you should still
+default the variable to something, but make the tasks that use the variable either fail
+gracefully without that var or prompt the user to define it if it's mandatory.
+
+If the variable is something that might need to be defined with a value specific to the lab in use, then
+it'll need to be added to your ``secrets`` repo as well. Variables in ``group_vars/all.yml`` will
+apply to all nodes unless a group_var file exists that is more specific for that node.  For example,
+if you define the var ``foo: bar`` in ``all.yml`` and the node you're running ansible against exists
+in the ``testnodes`` group and there is a ``group_vars/testnodes.yml`` file defined with
+``foo: baz`` included in it then the role using the variable will use the value defined in
+``testnodes.yml``. The playbook you're using knows which group_var file to use because of
+the ``hosts`` value defined for it.
+
+
 Setting up a local dev environment
 ==================================