Add instructions for third-party-check

These are instructions about how to set up OpenStack's Zuul to
report on changes to non-OpenStack projects.

Change-Id: I5b57abaf744fcf30ef815cc073fee5e5d91b445e
Depends-On: https://review.openstack.org/545065

doc/source/drivers.rst

@@ -755,3 +755,80 @@ So, this would change the initial list of names as follows:
 * gate-neutron-docs-ubuntu-xenial -> build-sphinx-docs
 * neutron-docs-ubuntu-xenial -> publish-sphinx-docs
 * legacy-tempest-dsvm-nova-lvm -> nova-lvm
+
+Outbound Third-Party Testing
+============================
+
+Many organizations generously donate cloud computing resources to the
+OpenStack project for use by its testing and automation system so that
+we can maintain and improve the quality of our software.  We are
+stewards of these resources and strive to use them wisely and
+responsibly.
+
+These resources are available to perform integration testing with
+Open-Source projects which are direct dependencies or direct
+downstream consumers of official OpenStack projects.  If you want to
+set up an integration test with a non-OpenStack project that meets
+these criteria, follow the instructions below.
+
+Currently, Zuul is able to report on changes proposed to Gerrit
+systems or GitHub.  If the project you want to test with isn't hosted
+on a Gerrit or GitHub, contact the infrastructure team in
+#openstack-infra to discuss options.
+
+In all cases, before starting this process, be sure you have discussed
+this with the team responsible for the project you want to test.  You
+should get their approval to report test results on changes or
+pull-requests.
+
+Hosted on an External Gerrit
+----------------------------
+
+If the project you wish to test is hosted on a Gerrit system (other
+than OpenStack's Gerrit), you may need to connect Zuul to it first, if
+it isn't already.  To do so, propose a change to `system-config
+<http://git.openstack.org/cgit/openstack-infra/system-config/tree/hiera/group/zuul-scheduler.yaml>`_
+which adds the connection information for the new server, then work
+with the infra team in #openstack-infra to set up an account.
+
+Once this is complete, propose a change to add the project(s) to
+OpenStack's Zuul.  Add them to `project-config/zuul/main.yaml
+<http://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul/main.yaml>`_
+under the connection name established above.
+
+The project should not be configured to load any configuration objects
+(i.e., it should have an ``include: []`` stanza associated with it).
+
+Hosted on GitHub
+----------------
+
+If the project you wish to test is hosted on GitHub, ask the team
+managing the project to install the "OpenStack Zuul" App into the
+project (or organization if multiple projects are involved).
+
+Visit the `OpenStack Zuul App
+<https://github.com/apps/openstack-zuul>`_ page on GitHub and click
+the `Configure` button to install the app.
+
+Once this is complete, propose a change to add the project(s) to
+OpenStack's Zuul.  Add them to `project-config/zuul/main.yaml
+<http://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul/main.yaml>`_
+under the ``github:`` connection.
+
+The project should not be configured to load any configuration objects
+(i.e., it should have an ``include: []`` stanza associated with it).
+
+Add to Pipelines
+----------------
+
+Once Zuul is configured to know about the project, it can be added to
+pipelines just like any other project in Zuul.  However, external
+projects should only be added to the ``third-party-check`` pipeline.
+Because we are not loading any in-tree configuration from these
+projects, this needs to be done in the `project-config` repo.  Define
+the jobs you wish to run either in your own repos, or in
+`openstack-zuul-jobs`.  Then create project definitions for the new
+projects in `project-config/zuul.d/projects.yaml
+<http://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul.d/projects.yaml>`_
+which adds those jobs to the new project on the `third-party-check`
+pipeline.