From d134c6ddf0e2c150bc25c02764c323e0f033c7fb Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Wed, 26 Jul 2017 16:09:34 -0700 Subject: [PATCH] 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 --- doc/source/admin/drivers/gerrit.rst | 103 +++++++++++++++++++++++++- doc/source/admin/drivers/github.rst | 108 ++++++++++++++++++++++++++++ doc/source/admin/drivers/zuul.rst | 13 ---- doc/source/user/config.rst | 79 ++++---------------- zuul/configloader.py | 15 ---- zuul/driver/zuul/zuultrigger.py | 8 --- 6 files changed, 221 insertions(+), 105 deletions(-) diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst index 29e136be64..e46bb63117 100644 --- a/doc/source/admin/drivers/gerrit.rst +++ b/doc/source/admin/drivers/gerrit.rst @@ -146,8 +146,8 @@ The supported pipeline trigger options are: 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 - `. For each specified criteria there must - exist a matching 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 @@ with a value. For example, ``verified: 1`` becomes ``gerrit review A :ref:`connection` that uses the gerrit driver must be supplied to the trigger. + +Requirements Configuration +-------------------------- + +As described in :ref:`pipeline.require ` and +:ref:`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. + + 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. + + 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 `. + + Example to reject a change with any negative vote:: + + reject: + my-gerrit: + approval: + - code-review: [-1, -2] diff --git a/doc/source/admin/drivers/github.rst b/doc/source/admin/drivers/github.rst index 91cef1b36e..661932286b 100644 --- a/doc/source/admin/drivers/github.rst +++ b/doc/source/admin/drivers/github.rst @@ -194,3 +194,111 @@ supplied to the reporter. It has the following options: Request based events. ``unlabel: 'test failed'`` .. _Github App: https://developer.github.com/apps/ + +Requirements Configuration +-------------------------- + +As described in :ref:`pipeline.require ` and +:ref:`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 GitHub +source named *my-github*, create a congfiguration such as the +following:: + + pipeline: + require: + my-github: + review: + - type: approval + +This indicates that changes originating from the GitHub connection +named *my-github* must have an approved code review in order to be +enqueued into the pipeline. + +.. zuul:configobject:: pipeline.require. + + The dictionary passed to the GitHub pipeline `require` attribute + supports the following attributes: + + .. _github-pipeline-require-review: + + .. zuul:attr:: review + + This requires that a certain kind of code review be present for + the pull request (it 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 a code review + matching all specified requirements. + + .. zuul:attr:: username + + If present, a code review from this username is required. It + is treated as a regular expression. + + .. zuul:attr:: email + + If present, a code review with this email address is + required. It is treated as a regular expression. + + .. zuul:attr:: older-than + + If present, the code review 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 code review must be newer than this amount of + time to match. Same format as "older-than". + + .. zuul:attr:: type + + If present, the code review must match this type (or types). + + .. TODO: what types are valid? + + .. zuul:attr:: permission + + If present, the author of the code review must have this + permission (or permissions). The available values are + ``read``, ``write``, and ``admin``. + + .. 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 item must be associated with the latest commit in the pull + request in order to be enqueued. + + .. TODO: this could probably be expanded upon -- under what + circumstances might this happen with github + + .. zuul:attr:: status + + A string value that corresponds with the status of the pull + request. The syntax is ``user:status:value``. + + .. zuul:attr:: label + + A string value indicating that the pull request must have the + indicated label (or labels). + + +.. zuul:configobject:: pipeline.reject. + + 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:: review + + This takes a list of code reviews. If a code review matches the + provided criteria the pull request can not be entered into the + pipeline. It follows the same syntax as the :ref:`review + pipeline requirement above `. diff --git a/doc/source/admin/drivers/zuul.rst b/doc/source/admin/drivers/zuul.rst index a23c875a2d..b5317543d7 100644 --- a/doc/source/admin/drivers/zuul.rst +++ b/doc/source/admin/drivers/zuul.rst @@ -25,16 +25,3 @@ can simply be used by listing **zuul** as the trigger. **pipeline** Only available for ``parent-change-enqueued`` events. This is the name of the pipeline in which the parent change was enqueued. - -**require-approval** - This may be used for any event. It 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 follows the - same syntax as the :ref:`"approval" pipeline requirement - `. For each specified criteria there must - exist a matching approval. - -**reject-approval** - This takes a list of approvals in the same format as - *require-approval* but will fail to enter the pipeline if there is a - matching approval. diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst index 362edad3d2..2ef581a802 100644 --- a/doc/source/user/config.rst +++ b/doc/source/user/config.rst @@ -234,68 +234,22 @@ success, the pipeline reports back to Gerrit with a *Verified* vote of of the connection will dictate which options are available. See :ref:`drivers`. + .. _pipeline-require: + .. zuul:attr:: require - If this section is present, it established pre-requisites for + If this section is present, it establishes pre-requisites for any kind of item entering the Pipeline. Regardless of how the item is to be enqueued (via any trigger or automatic dependency resolution), the conditions specified here must be met or the - item will not be enqueued. + item will not be enqueued. These requirements may vary + depending on the source of the item being enqueued. - .. _pipeline-require-approval: + Requirements are loaded from their connection name. The driver + type of the connection will dictate which options are available. + See :ref:`drivers`. - .. 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. + .. _pipeline-reject: .. zuul:attr:: reject @@ -303,18 +257,9 @@ success, the pipeline reports back to Gerrit with a *Verified* vote of can block an item from being enqueued. It can be considered a negative version of **require**. - .. 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:`"require - approval" pipeline above `. - - Example to reject a change with any negative vote:: - - reject: - approval: - - code-review: [-1, -2] + Requirements are loaded from their connection name. The driver + type of the connection will dictate which options are available. + See :ref:`drivers`. .. zuul:attr:: dequeue-on-new-patchset diff --git a/zuul/configloader.py b/zuul/configloader.py index 51949d4451..3fc10b8c08 100644 --- a/zuul/configloader.py +++ b/zuul/configloader.py @@ -762,19 +762,6 @@ class PipelineParser(object): precedence = vs.Any('normal', 'low', 'high') - approval = vs.Schema({'username': str, - 'email': str, - 'older-than': str, - 'newer-than': str, - }, extra=vs.ALLOW_EXTRA) - - require = {'approval': to_list(approval), - 'open': bool, - 'current-patchset': bool, - 'status': to_list(str)} - - reject = {'approval': to_list(approval)} - window = vs.All(int, vs.Range(min=0)) window_floor = vs.All(int, vs.Range(min=1)) window_type = vs.Any('linear', 'exponential') @@ -784,8 +771,6 @@ class PipelineParser(object): vs.Required('manager'): manager, 'precedence': precedence, 'description': str, - 'require': require, - 'reject': reject, 'success-message': str, 'failure-message': str, 'merge-failure-message': str, diff --git a/zuul/driver/zuul/zuultrigger.py b/zuul/driver/zuul/zuultrigger.py index 09125f27ee..7757a31c29 100644 --- a/zuul/driver/zuul/zuultrigger.py +++ b/zuul/driver/zuul/zuultrigger.py @@ -43,19 +43,11 @@ class ZuulTrigger(BaseTrigger): def getSchema(): - approval = v.Schema({'username': str, - 'email': str, - 'older-than': str, - 'newer-than': str, - }, extra=v.ALLOW_EXTRA) - zuul_trigger = { v.Required('event'): scalar_or_list(v.Any('parent-change-enqueued', 'project-change-merged')), 'pipeline': scalar_or_list(str), - 'require-approval': scalar_or_list(approval), - 'reject-approval': scalar_or_list(approval), } return zuul_trigger