Add intro for testers

Signed-off-by: Zack Cerza <zack@redhat.com>

diff --git a/docs/README.rst b/docs/README.rst
index a1fb3c65b8227f876acdd908e7f014ff1b6837ed..dc4a00abfc0259010d86ba11b2fac88e47d33464 100644 (file)
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -23,6 +23,9 @@ operations on remote hosts over SSH, as implemented by `Paramiko
 
 When testing, it is common to group many `jobs` together to form a `test run`.
 
+If you are new to teuthology and simply want to run existing tests, check out
+:ref:`intro_testers`
+
 
 Provided Utilities
 ==================

diff --git a/docs/index.rst b/docs/index.rst
index d01f6be13a373661b5d0eb9074d1efd35b25425a..4a8b110ef884301bd300edfa4cf5ee04d2770520 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,6 +5,7 @@ Content Index
    :maxdepth: 2
 
    README.rst
+   intro_testers.rst
    siteconfig.rst
    openstack_backend.rst
    INSTALL.rst

diff --git a/docs/intro_testers.rst b/docs/intro_testers.rst
new file mode 100644 (file)
index 0000000..d4f3289
--- /dev/null
+++ b/docs/intro_testers.rst
@@ -0,0 +1,61 @@
+.. _intro_testers:
+
+========================
+Introduction for Testers
+========================
+
+This document is aimed at providing an introduction to running existing test suites.
+
+We assume here that you have access to an operational test lab; if not, ask
+your local admin for access!
+
+If you're here to test upstream Ceph, start `here
+<http://ceph.github.io/sepia/adding_users/>`__.
+
+
+Terminology
+===========
+
+In the abstract, each set of tests is defined by a `suite`. All of our suites
+live in the `ceph-qa-suite repository
+<https://github.com/ceph/ceph-qa-suite/>`__, in the `suites` subdirectory.
+
+In concrete terms, a `run` is what is created by assembling the contents of a
+`suite` into a number of `jobs`. A `job` is created by assembling a number of
+`fragments` (also known as `facets`) together. Each `fragment` is in `YAML
+<http://yaml.org/>`__ format.
+
+Each `job` definition contains a list of `tasks` to execute, along with
+`roles`. `Roles` tell `teuthology` how many nodes to use for each `job` along
+with what functions each node will perform.
+
+To go into more depth regarding suite design, see `ceph-qa-suite`'s `README`.
+
+One example of this is the `smoke
+<https://github.com/ceph/ceph-qa-suite/tree/master/suites/smoke>`__ suite.
+
+
+Scheduling
+==========
+Most testing happens by scheduling `runs`. The way we do that is using the
+`teuthology-suite` command.
+
+To get a preview of what `teuthology-suite` might do, try::
+
+    teuthology-suite -v -s smoke -c master -m mira --dry-run
+
+Assuming a build is available, that should pretend to schedule several jobs. If
+it complains about missing packages, try swapping `master` with `jewel` or one
+of the other Ceph stable branches.
+
+To see even more detail, swap `-v` with `-vv`. It will print out each job
+definition in full. To limit the number of jobs scheduled, you may want to use
+the `--limit`, `--filter`, or `--filter-out` flags.
+
+To actually schedule, drop `--dry-run` and optionally use the `--email` flag to
+get an email when the test run completes.
+
+`teuthology-suite` also prints out a link to the run in `pulpito
+<https://github.com/ceph/pulpito/>`__ that will display the current status of
+each job. The Sepia lab's pulpito instance is `here
+<http://pulpito.ceph.com/>`__.