Added examples of how roles work!

examples/playbooks/roles/foo/files/foo.txt

+This is a file
+

examples/playbooks/roles/foo/handlers/main.yml

+---
+
+- name: blippy
+  shell: echo notifier called, and the value of x is '{{ x }}'
+
+

examples/playbooks/roles/foo/main.yml

+---
+
+- name: template operation
+  template: src=foo.j2 dest=/etc/motd
+
+- action: shell echo 'hi webserver'
+  notify:
+    - blippy

examples/playbooks/roles/foo/tasks/main.yml

+---
+
+- name: copy operation
+  copy: src=foo.txt dest=/tmp/roles_test1.txt
+
+- name: template operation
+  template: src=foo.j2 dest=/tmp/roles_test2.txt
+  notify:
+    - blippy

examples/playbooks/roles/foo/templates/foo.j2

+I am a {{ ansible_os_family }} distribution.

examples/playbooks/roles/foo/vars/main.yml

+---
+x: '{{ ansible_machine }}'
+

examples/playbooks/roletest.yml

+# in Ansible 1.2 and later, roles allow easy best-practices organization of content 
+# and maximize shareability of ansible building blocks.
+#
+# suppose a playbook applied to a group of hosts includes two roles, foo and bar.
+#
+# what do roles do in this case?
+#
+# listing the roles as foo and bar will auto include the following:
+#
+#    tasks    from ./roles/foo/tasks/main.yml,    then ./roles/bar/tasks/main.yml
+#    handlers from ./roles/foo/handlers/main.yml, then ./roles/bar/handlers/main.yml
+#    vars     from ./roles/foo/vars/main.yml,     then ./roles/bar/vars/main.yml
+#
+# should any of these files not exist, that is ok, and they will simply not be loaded.
+#
+# should the task file in foo/tasks/main.yml want to include subtasks in other files, that
+# is also permitted.
+#
+# templates and copy operations also get smarter about where to look for content when using
+# roles.
+# 
+# as an example, a task in foo/tasks/main.yml could copy or template a file by
+# referencing a "src=foo.j2" rather than having to explicitly path src=roles/foo/templates/foo.j2.
+
+---
+
+  - hosts: all
+    roles:
+      - foo
+
+    # add as many roles as you like, roles takes a list of roles names
+    # these paths can be qualified, but if bare, it will look from them in
+    # roles/$rolename relative to the playbook
+    #
+    # - bar
+
+    # explicit tasks and handlers can be used, but are not required.
+    # they will run after the roles if present.
+

lib/ansible/playbook/play.py

@@ -127,11 +127,13 @@ class Play(object):
         new_vars_files = []
         for orig_path in roles:
             path = utils.path_dwim(self.basedir, orig_path)
-            if not os.path.isdir(path):
-                path2 = utils.path_dwim(self.basedir, os.path.join(self.basedir, 'roles', orig_path))
+            if not os.path.isdir(path) and not orig_path.startswith(".") and not orig_path.startswith("/"):
+                path2 = utils.path_dwim(self.basedir, os.path.join('roles', orig_path))
                 if not os.path.isdir(path2):
                     raise errors.AnsibleError("cannot find role in %s or %s" % (path, path2))
                 path = path2
+            elif not os.path.isdir(path):
+                raise errors.AnsibleError("cannot find role in %s" % (path))
             task      = utils.path_dwim(self.basedir, os.path.join(path, 'tasks', 'main.yml'))
             handler   = utils.path_dwim(self.basedir, os.path.join(path, 'handlers', 'main.yml'))
             vars_file = utils.path_dwim(self.basedir, os.path.join(path, 'vars', 'main.yml'))