add reproducer-quickstart.sh documentation

Create some community level documentation for the
TripleO CI recreate tooling in upstream.

Change-Id: I7f24f7cfd58869dd728071163a43edcc0f0c7333

doc/source/contributor/index.rst

@@ -7,6 +7,7 @@ TripleO Contributor Guide
 
   new_developers
   contributions
+  reproduce-ci
   check_gates
   dlrn-promoter-overview
   stages-overview

doc/source/contributor/reproduce-ci.rst

@@ -0,0 +1,98 @@
+Reproduce CI jobs for debugging and development
+===============================================
+
+Reproducing any given CI job that is executed upstream is critical for
+development.  You will find a script called "reproducer-quickstart.sh" under
+the logs directory of any TripleO CI job that will assist you in recreating a
+TripleO Quickstart upstream job.
+
+Each script contains the same parameters used in the job and includes any
+deployment or CI related settings.  Any patches that were marked as
+dependencies will also be included in the script and execution.
+
+This script will provision a heat stack in an OpenStack host cloud that matches
+the environment created by nodepool or `OVB <http://openstack-virtual-baremetal.
+readthedocs.io/en/latest/introduction.html>`_ upstream.  Once the environment
+is ready, the script prompts the user with some additional instructions that
+executes the same scripts and tools used upstream to bootstrap and execute the
+CI.
+
+How to execute the reproducer-quickstart script
+-----------------------------------------------
+
+Go to the "logs" directory of the job::
+
+    wget http://logs.openstack.org/07/472607/<snip>/f98d674/logs/
+    reproducer-quickstart.sh
+
+Source your OpenStack RC file::
+
+    source openstack_rc.sh
+
+Execute the reproducer-quickstart.sh::
+
+    bash -x reproducer-quickstart.sh
+
+The following additional options are recommended::
+
+    bash -x reproducer-quickstart.sh --workspace /var/tmp/reproduce
+    --create-virtualenv true -remove-stack-keypairs true
+    --nodestack-prefix repro
+
+Please check the script's help command however the available options are::
+
+
+  Options:
+  -w, --workspace <dir>
+                      directory where the virtualenv, inventory files, etc.
+                      are created. Defaults to creating a directory in /tmp
+  -v, --create-virtualenv
+                      create a virtualenv to install Ansible and dependencies.
+                      Options to pass true/false. Defaults to true for OVB.
+                      Defaults to false for other deployment types.
+  -r, --remove-stacks-keypairs
+                      delete all Heat stacks (both Multinode and OVB created)
+                      in the tenant before deployment.
+                      Will also delete associated keypairs if they exist.
+                      Options to pass true/false.Defaults to false.
+  -p, --nodestack-prefix
+                      add a unique prefix for multinode and singlenode stacks
+                      Defaults to empty.
+  -a, --autorun
+                      Run job on prepared environment automatically
+                      Default is to stop after environment is ready
+  -h, --help          print this help and exit
+
+How does this script work
+-------------------------
+
+The script is generated by a `jinja2 template <https://github.com/openstack/
+tripleo-quickstart-extras/blob/master/roles/create-reproducer-script/templates/
+reproducer-quickstart.sh.j2>`_ that reads all the variables passed to the CI job
+and builds a custom script for each job.  There are two major steps to be
+amiliar with in this script.  The first part of the script will provision the
+servers, networks and other infrastructure for the TripleO deployment.  The
+second part invokes the CI tools and scripts in the `same way the original CI
+job was executed <https://github.com/openstack-infra/tripleo-ci/blob/master/
+toci_gate_test-oooq.sh>`_.
+
+Notes
+-----
+
+If the environment was provisioned successfully you will be presented with
+further instructions that will prompt you to ssh to the environment and execute
+the upstream CI scripts.  You may elect to run this automatically with the
+"autorun" option found in the help.
+
+Support
+-------
+
+The TripleO CI team will provide community support for the
+reproducer-quickstart.sh script.  The tool is only supported in use with an
+OpenStack host cloud.  Your results with various OpenStack providers may vary.
+Please open any issues or problems in
+`launchpad <https://bugs.launchpad.net/tripleo>`_ with the "quickstart" tag.
+
+The `devmode.sh <https://github.com/openstack/tripleo-quickstart/blob/master/
+devmode.sh>`_ script is deprecated.  The reproducer-quickstart.sh should be
+used for upstream development and debugging of TripleO CI.