Adding documentation on role dependencies and variable scope/inheritance

docsite/latest/rst/playbooks.rst

@@ -466,12 +466,14 @@ Example project structure::
          tasks/
          handlers/
          vars/
+         meta/
        webservers/
          files/
          templates/
          tasks/
          handlers/
          vars/
+         meta/
 
 In a playbook, it would look like this::
 
@@ -486,10 +488,14 @@ This designates the following behaviors, for each role 'x':
 - If roles/x/tasks/main.yml exists, tasks listed therein will be added to the play
 - If roles/x/handlers/main.yml exists, handlers listed therein will be added to the play
 - If roles/x/vars/main.yml exists, variables listed therein will be added to the play
+- If roles/x/meta/main.yml exists, any role dependencies listed therein will be added to the list of roles
 - Any copy tasks can reference files in roles/x/files/ without having to path them relatively or absolutely
 - Any script tasks can reference scripts in roles/x/files/ without having to path them relatively or absolutely
 - Any template tasks can reference files in roles/x/templates/ without having to path them relatively or absolutely
 
+.. note::
+   Role dependencies are discussed below.
+
 If any files are not present, they are just ignored.  So it's ok to not have a 'vars/' subdirectory for the role,
 for instance.
 
@@ -544,6 +550,99 @@ If you want to define certain tasks to happen before AND after roles are applied
    be sure to also tag your pre_tasks and post_tasks and pass those along as well, especially if the pre
    and post tasks are used for monitoring outage window control or load balancing.
 
+Role Dependencies
+`````````````````
+
+.. versionadded: 1.3
+
+Role dependencies allow you to include other roles within your role, so that you no longer
+have to specify them at the top level. As noted above, role dependencies are stored in the
+`meta/main.yml` file contained within the role directory. This file should contain the following::
+
+    ---
+    dependencies:
+    - { role: foo, x: 1 }
+    - { role: bar, y: 2 }
+    - { role: baz, z: 3 }
+
+Role dependencies can also be specified as a full path::
+
+    ---
+    dependencies:
+    - { role: '/path/to/common/roles/foo', x: 1 }
+
+Roles dependencies are always executed before the role that includes them. For example, given the following
+list of dependant roles::
+
+    - car
+      - wheel
+        - tire
+        - brake
+
+The roles would be executed in the order: tire -> brake -> wheel -> car.
+
+Role dependencies may be included more than once. Continuing the above example, the car role could 
+add dependencies as follows::
+
+    ---
+    dependencies:
+    - { role: wheel, n: 1 }
+    - { role: wheel, n: 2 }
+    - { role: wheel, n: 3 }
+    - { role: wheel, n: 4 }
+
+Which would result in the following dependency tree::
+
+    - car
+      - wheel (n=1)
+        - tire (n=1)
+        - brake (n=1)
+      - wheel (n=2)
+        - tire (n=2)
+        - brake (n=2)
+      - wheel (n=3)
+        - tire (n=3)
+        - brake (n=3)
+      - wheel (n=4)
+        - tire (n=4)
+        - brake (n=4)
+
+And the order of execution would be tire(n=1) -> brake(n=1) -> wheel(n=1) -> tire(n=2) -> brake(n=2) -> wheel(n=2) -> ... -> car.
+
+.. note::
+   Variable inheritance and scope are detailed below.
+
+Role Variable Scope and Precedence
+``````````````````````````````````
+
+There are two rules governing variable scope when it comes to roles and dependencies.
+
+1. Variables listed in vars/ files are loaded into the role and also into the global list of variables.
+
+This means that if two roles define the same variable name, the last one to be included will be the 
+one that sets the variable at the global level. These variables also override whatever may be set in group
+or host vars files, since inventory variables have the lowest priority.
+
+This allows roles to share variables with other roles that it doesn't know about, and means variables from 
+parent roles will override any that are set at a lower level. Given the car/wheel example above, if the 
+`tire` role sets `x: 1` in its vars/main.yml while the `wheel` roles sets `x: 2`, both roles will see 
+`x: 2` (as will the brake role). This allows parent roles to override variables defined in dependant classes, 
+for instance if you wanted to override the http_port setting in a web server role. 
+
+If you wish to avoid this behavior, make sure the variables in your roles have unique names instead of something 
+generic like `port`.
+
+2. Variables given when including/depending a role override variables in vars/main.yml
+
+This means that if you include a role (or add it to a list of dependencies) while setting a variable, 
+that variable value will be the one that role (and any dependant roles) will see.
+
+For example, given the car/wheel example again, if the car adds the wheel role as a dependency as follows::
+
+    - { role: wheel, x: 100 }
+
+Then the wheel, tire, and brake roles will all see `x: 100` no matter what is set in the vars files for each role.
+
 Executing A Playbook
 ````````````````````
 

docsite/latest/rst/playbooks2.rst

@@ -1101,7 +1101,7 @@ Which of course means that, though more verbose, this is also legal syntax::
 Local Facts (Facts.d)
 `````````````````````
 
-.. version_added:: 1.3
+.. versionadded:: 1.3
 
 As discussed in the playbooks chapter, Ansible facts are a way of getting data about remote systems for use in playbook variables.
 Usually these are discovered automatically by the 'setup' module in Ansible. Users can also write custom facts modules, as described