zuul
/
zuul
Code Issues Proposed changes

Merge "Docs: group matchers together and explain them" into feature/zuulv3

This commit is contained in:
Zuul 2017-12-14 17:07:07 +00:00 committed by Gerrit Code Review
parent caf2e4c9c1 5a2bce767a
commit 9dc1b9f000
1 changed files with 93 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
doc/source/user/config.rst
View File

@ -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