Separate reporters from triggers
Allows multiple reports per a patchset to be sent to pluggable
destinations. These are configurable per pipeline and, if not
specified, defaults to the legacy behaviour of reporting back only
to gerrit.
Having multiple reporting methods means only certain success/failure
/start parameters will apply to certain reporters. Reporters are
listed as keys under each of those actions.
This means that each key under success/failure/start is a reporter and the
dictionaries under those are sent to the reporter to deal with.
Change-Id: I80d7539772e1485d5880132f22e55751b25ec198
diff --git a/doc/source/reporters.rst b/doc/source/reporters.rst
new file mode 100644
index 0000000..d64d4f7
--- /dev/null
+++ b/doc/source/reporters.rst
@@ -0,0 +1,32 @@
+:title: Reporters
+
+Reporters
+=========
+
+Zuul can communicate results and progress back to configurable
+protocols. For example, after succeeding in a build a pipeline can be
+configured to post a positive review back to gerrit.
+
+There are three stages when a report can be handled. That is on:
+Start, Success or Failure. Each stage can have multiple reports.
+For example, you can set verified on gerrit and send an email.
+
+Gerrit
+------
+
+Zuul works with standard versions of Gerrit by invoking the
+``gerrit`` command over an SSH connection. It reports back to
+Gerrit using SSH.
+
+The dictionary passed to the gerrit reporter is used for ``gerrit
+review`` arguments, with the boolean value of ``true`` simply
+indicating that the argument should be present without following it
+with a value. For example, ``verified: 1`` becomes ``gerrit review
+--verified 1`` and ``submit: true`` becomes ``gerrit review
+--submit``.
+
+Gerrit Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+The configuration for posting back to gerrit is shared with the gerrit
+trigger in zuul.conf. Please consult the gerrit trigger documentation.