Merge "Update contributiing docs for readability and correctness"

doc/source/contributing.rst

@@ -5,6 +5,9 @@ Contributing
 Adding roles into this project is easy and starts with a compatible skeleton.
 
 
+Create a new role manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 From with the project root, creating a skeleton for the new role.
 
 .. code-block:: console
@@ -22,8 +25,7 @@ the `tox.ini` file as an test scenario.
     deps={[testenv:mol]deps}
     changedir = {toxinidir}/tripleo_ansible/roles/${NEWROLENAME}
     envdir = {toxworkdir}/mol
-    commands =
-      python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py
+    commands = python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py
 
 
 If a given role has more than one scenario to test, the `--scenario` argument
@@ -36,44 +38,50 @@ can be used to set the scenario accordingly.
     deps={[testenv:mol-${NEWROLENAME}]deps}
     changedir = {[testenv:mol-${NEWROLENAME}]changedir}
     envdir = {[testenv:mol-${NEWROLENAME}]envdir}
-    commands =
-      python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py --scenario=${SCENARIO_2}
+    commands = python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py --scenario=${SCENARIO_2}
 
 
-When the role is ready for CI add a jobs entry into the `zuul.d/jobs.yaml`.
+When the role is ready for CI, add a **job** entry into the `zuul.d/molecule.yaml`.
 
 .. code-block:: yaml
 
     - job:
-        name: tripleo-ansible-centos:mol-${NEWROLENAME}
-        parent: tripleo-ansible-centos
         files:
         - ^tripleo_ansible/roles/${NEWROLENAME}/.*
+        name: tripleo-ansible-centos-7-molecule-${NEWROLENAME}
+        parent: tripleo-ansible-centos
         vars:
           tox_envlist: mol-${NEWROLENAME}
 
 
-Add the job into the `zuul.d/layout.yaml` file.
+Make sure to add the **job** name into the check and gate section at the top of
+the `molecule.yaml` file.
 
 .. code-block:: yaml
 
     - project:
         check:
           jobs:
-            - tripleo-ansible-centos:mol-${NEWROLENAME}
+            - tripleo-ansible-centos-7-molecule-${NEWROLENAME}
+        gate:
+          jobs:
+            - tripleo-ansible-centos-7-molecule-${NEWROLENAME}
 
 
-And finally add a role documentation file at
+Finally add a role documentation file at
 `doc/source/roles/role-${NEWROLENAME}.rst`. This file will need to contain
 a title, a literal include of the defaults yaml and a literal include of
-the molecule playbook used to test the role, which is noted as an "example"
-playbook.
+the molecule playbook, or playbooks, used to test the role, which is noted
+as an "example" playbook.
 
 
+Create a new role with automation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The role addition process is also automated using ansible. If ansible is
 available on the development workstation change directory to the root of
 the `tripleo-ansible` repository and run the the following command which
-will perform all of the tasks noted above.
+will perform the basic tasks noted above.
 
 .. code-block:: console
 

doc/source/roles/role-tripleo-transfer.rst

@@ -1,6 +1,6 @@
-=======================================
-TripleO-Ansible Role - tripleo-transfer
-=======================================
+=======================
+Role - tripleo-transfer
+=======================
 
 This role provides for the following services: