From 5a2bce767a80a330d7a8a34c6bc63c69e43ec317 Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Wed, 13 Dec 2017 09:24:30 -0800 Subject: [PATCH] Docs: group matchers together and explain them Change-Id: Ib14e8c81edc35e5900b89dd46ba5b3dc4a41fd08 --- doc/source/user/config.rst | 179 +++++++++++++++++++------------------ 1 file changed, 93 insertions(+), 86 deletions(-) diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst index 4151eda113..173e615e5e 100644 --- a/doc/source/user/config.rst +++ b/doc/source/user/config.rst @@ -609,92 +609,6 @@ Here is an example of two job definitions: tags from all the jobs and variants used in constructing the frozen job, with no duplication. - .. attr:: branches - - A regular expression (or list of regular expressions) which - describe on what branches a job should run (or in the case of - variants: to alter the behavior of a job for a certain branch). - - If there is no job definition for a given job which matches the - branch of an item, then that job is not run for the item. - Otherwise, all of the job variants which match that branch (and - any other selection criteria) are used when freezing the job. - - This example illustrates a job called *run-tests* which uses a - nodeset based on the current release of an operating system to - perform its tests, except when testing changes to the stable/2.0 - branch, in which case it uses an older release: - - .. code-block:: yaml - - - job: - name: run-tests - nodeset: current-release - - - job: - name: run-tests - branches: stable/2.0 - nodeset: old-release - - In some cases, Zuul uses an implied value for the branch - specifier if none is supplied: - - * For a job definition in a :term:`config-project`, no implied - branch specifier is used. If no branch specifier appears, the - job applies to all branches. - - * In the case of an :term:`untrusted-project`, if the project - has only one branch, no implied branch specifier is applied to - :ref:`job` definitions. If the project has more than one - branch, the branch containing the job definition is used as an - implied branch specifier. - - * In the case of a job variant defined within a :ref:`project`, - if the project definition is in a :term:`config-project`, no - implied branch specifier is used. If it appears in an - :term:`untrusted-project`, with no branch specifier, the - branch containing the project definition is used as an implied - branch specifier. - - * In the case of a job variant defined within a - :ref:`project-template`, if no branch specifier appears, the - implied branch containing the project-template definition is - used as an implied branch specifier. This means that - definitions of the same project-template on different branches - may run different jobs. - - When that project-template is used by a :ref:`project` - definition within a :term:`untrusted-project`, the branch - containing that project definition is combined with the branch - specifier of the project-template. This means it is possible - for a project to use a template on one branch, but not on - another. - - This allows for the very simple and expected workflow where if a - project defines a job on the ``master`` branch with no branch - specifier, and then creates a new branch based on ``master``, - any changes to that job definition within the new branch only - affect that branch, and likewise, changes to the master branch - only affect it. - - See :attr:`pragma.implied-branch-matchers` for how to override - this behavior on a per-file basis. - - .. attr:: files - - This attribute indicates that the job should only run on changes - where the specified files are modified. This is a regular - expression or list of regular expressions. - - .. attr:: irrelevant-files - - This is a negative complement of **files**. It indicates that - the job should run unless *all* of the files changed match this - list. In other words, if the regular expression ``docs/.*`` is - supplied, then this job will not run if the only files changed - are in the docs directory. A regular expression or list of - regular expressions. - .. attr:: secrets A list of secrets which may be used by the job. A @@ -957,6 +871,99 @@ Here is an example of two job definitions: it will remain set for all child jobs and variants (it can not be set to ``false``). + .. _matchers: + + The following job attributes are considered "matchers". They are + not inherited in the usual manner, instead, these attributes are + used to determine whether a specific variant is used when + running a job. + + .. attr:: branches + + A regular expression (or list of regular expressions) which + describe on what branches a job should run (or in the case of + variants: to alter the behavior of a job for a certain branch). + + If there is no job definition for a given job which matches the + branch of an item, then that job is not run for the item. + Otherwise, all of the job variants which match that branch (and + any other selection criteria) are used when freezing the job. + + This example illustrates a job called *run-tests* which uses a + nodeset based on the current release of an operating system to + perform its tests, except when testing changes to the stable/2.0 + branch, in which case it uses an older release: + + .. code-block:: yaml + + - job: + name: run-tests + nodeset: current-release + + - job: + name: run-tests + branches: stable/2.0 + nodeset: old-release + + In some cases, Zuul uses an implied value for the branch + specifier if none is supplied: + + * For a job definition in a :term:`config-project`, no implied + branch specifier is used. If no branch specifier appears, the + job applies to all branches. + + * In the case of an :term:`untrusted-project`, if the project + has only one branch, no implied branch specifier is applied to + :ref:`job` definitions. If the project has more than one + branch, the branch containing the job definition is used as an + implied branch specifier. + + * In the case of a job variant defined within a :ref:`project`, + if the project definition is in a :term:`config-project`, no + implied branch specifier is used. If it appears in an + :term:`untrusted-project`, with no branch specifier, the + branch containing the project definition is used as an implied + branch specifier. + + * In the case of a job variant defined within a + :ref:`project-template`, if no branch specifier appears, the + implied branch containing the project-template definition is + used as an implied branch specifier. This means that + definitions of the same project-template on different branches + may run different jobs. + + When that project-template is used by a :ref:`project` + definition within a :term:`untrusted-project`, the branch + containing that project definition is combined with the branch + specifier of the project-template. This means it is possible + for a project to use a template on one branch, but not on + another. + + This allows for the very simple and expected workflow where if a + project defines a job on the ``master`` branch with no branch + specifier, and then creates a new branch based on ``master``, + any changes to that job definition within the new branch only + affect that branch, and likewise, changes to the master branch + only affect it. + + See :attr:`pragma.implied-branch-matchers` for how to override + this behavior on a per-file basis. + + .. attr:: files + + This matcher indicates that the job should only run on changes + where the specified files are modified. This is a regular + expression or list of regular expressions. + + .. attr:: irrelevant-files + + This matcher is a negative complement of **files**. It + indicates that the job should run unless *all* of the files + changed match this list. In other words, if the regular + expression ``docs/.*`` is supplied, then this job will not run + if the only files changed are in the docs directory. A regular + expression or list of regular expressions. + .. _project: Project