Cleanup pipeline requirements
Pipeline requirements are now per-source. Remove dead validation
code in configloader which appeared to validate the old form (but
was actually overriden). Remove requirements from the zuul trigger
which are not used. Move the current requirements documentation
into the gerrit driver docs, and create github requirements docs.
Change-Id: I87e3813242dd3cd67138eae9efa96693fc598af0
diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
index 29e136b..e46bb63 100644
--- a/doc/source/admin/drivers/gerrit.rst
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -146,8 +146,8 @@
approval be present for the current patchset of the change (the
approval could be added by the event in question). It follows the
same syntax as the :ref:`"approval" pipeline requirement
- <pipeline-require-approval>`. For each specified criteria there must
- exist a matching approval.
+ <gerrit-pipeline-require-approval>`. For each specified criteria
+ there must exist a matching approval.
**reject-approval**
This takes a list of approvals in the same format as
@@ -170,3 +170,102 @@
A :ref:`connection<connections>` that uses the gerrit driver must be
supplied to the trigger.
+
+Requirements Configuration
+--------------------------
+
+As described in :ref:`pipeline.require <pipeline-require>` and
+:ref:`pipeline.reject <pipeline-reject>`, pipelines may specify that
+items meet certain conditions in order to be enqueued into the
+pipeline. These conditions vary according to the source of the
+project in question. To supply requirements for changes from a Gerrit
+source named *my-gerrit*, create a congfiguration such as the
+following::
+
+ pipeline:
+ require:
+ my-gerrit:
+ approval:
+ - code-review: 2
+
+This indicates that changes originating from the Gerrit connection
+named *my-gerrit* must have a Code Review vote of +2 in order to be
+enqueued into the pipeline.
+
+.. zuul:configobject:: pipeline.require.<source>
+
+ The dictionary passed to the Gerrit pipeline `require` attribute
+ supports the following attributes:
+
+ .. _gerrit-pipeline-require-approval:
+
+ .. zuul:attr:: approval
+
+ This requires that a certain kind of approval be present for the
+ current patchset of the change (the approval could be added by
+ the event in question). It takes several sub-parameters, all of
+ which are optional and are combined together so that there must
+ be an approval matching all specified requirements.
+
+ .. zuul:attr:: username
+
+ If present, an approval from this username is required. It is
+ treated as a regular expression.
+
+ .. zuul:attr:: email
+
+ If present, an approval with this email address is required. It is
+ treated as a regular expression.
+
+ .. zuul:attr:: older-than
+
+ If present, the approval must be older than this amount of time
+ to match. Provide a time interval as a number with a suffix of
+ "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
+ (seconds). Example ``48h`` or ``2d``.
+
+ .. zuul:attr:: newer-than
+
+ If present, the approval must be newer than this amount
+ of time to match. Same format as "older-than".
+
+ Any other field is interpreted as a review category and value
+ pair. For example ``Verified: 1`` would require that the
+ approval be for a +1 vote in the "Verified" column. The value
+ may either be a single value or a list: ``Verified: [1, 2]``
+ would match either a +1 or +2 vote.
+
+ .. zuul:attr:: open
+
+ A boolean value (``true`` or ``false``) that indicates whether
+ the change must be open or closed in order to be enqueued.
+
+ .. zuul:attr:: current-patchset
+
+ A boolean value (``true`` or ``false``) that indicates whether the
+ change must be the current patchset in order to be enqueued.
+
+ .. zuul:attr:: status
+
+ A string value that corresponds with the status of the change
+ reported by the trigger.
+
+.. zuul:configobject:: pipeline.reject.<source>
+
+ The `reject` attribute is the mirror of the `require` attribute. It
+ also accepts a dictionary under the connection name. This
+ dictionary supports the following attributes:
+
+ .. zuul:attr:: approval
+
+ This takes a list of approvals. If an approval matches the
+ provided criteria the change can not be entered into the
+ pipeline. It follows the same syntax as the :ref:`approval
+ pipeline requirement above <gerrit-pipeline-require-approval>`.
+
+ Example to reject a change with any negative vote::
+
+ reject:
+ my-gerrit:
+ approval:
+ - code-review: [-1, -2]