From 2da568a9eac68810184b948bf1e39243777b8f58 Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Fri, 6 Aug 2021 16:39:28 -0700 Subject: [PATCH] Update regex note The regex note applies generally to Zuul configuration syntax, so move it to the general page. To make it more relevant to each of the items which it specifically affects, hyperlink regex references to the note. Change-Id: Ia971f5d52496fd4ccdfa18db4c9e3d39c1351bdc --- doc/source/reference/config.rst | 11 +++++++++++ doc/source/reference/job_def.rst | 20 +++++++------------- doc/source/reference/pragma_def.rst | 2 +- doc/source/reference/tenants.rst | 16 ++++++++-------- 4 files changed, 27 insertions(+), 22 deletions(-) diff --git a/doc/source/reference/config.rst b/doc/source/reference/config.rst index 7ad87c1710..58dbecbd12 100644 --- a/doc/source/reference/config.rst +++ b/doc/source/reference/config.rst @@ -59,6 +59,17 @@ As soon as a change containing a Zuul configuration change merges to any Zuul-managed repository, the new configuration takes effect immediately. +.. _regex: + +Regular Expressions +------------------- + +Many options accept literal strings or regular expressions. In these +cases, the regular expression matching starts at the beginning of the +string as if there were an implicit ``^`` at the start of the regular +expression. To match at an arbitrary position, prepend ``.*`` to the +regular expression. + .. _configuration-items: Configuration Items diff --git a/doc/source/reference/job_def.rst b/doc/source/reference/job_def.rst index f25ae88954..7a26871224 100644 --- a/doc/source/reference/job_def.rst +++ b/doc/source/reference/job_def.rst @@ -78,13 +78,6 @@ Here is an example of two job definitions: - name: test-node label: fedora -.. warning:: - - Regular expression matching in Zuul *starts at the beginning of - the string*, i.e., as if there was an implicit ``^`` at the beginning - of the regular expression. To match at an arbitrary position, prepend - ``.*`` to the regular expression. - .. attr:: job The following attributes are available on a job; all are optional @@ -796,9 +789,10 @@ Here is an example of two job definitions: .. 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). + A :ref:`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). This attribute is not inherited in the usual manner. Instead, it is used to determine whether each variant on which it appears @@ -864,7 +858,7 @@ Here is an example of two job definitions: specified files are modified. Unlike **branches**, this value is subject to inheritance and overriding, so only the final value is used to determine if the job should run. This is a - regular expression or list of regular expressions. + :ref:`regular expression ` or list of regular expressions. .. attr:: irrelevant-files @@ -872,8 +866,8 @@ Here is an example of two job definitions: 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. + are in the docs directory. A :ref:`regular expression ` + or list of regular expressions. .. attr:: match-on-config-updates :default: true diff --git a/doc/source/reference/pragma_def.rst b/doc/source/reference/pragma_def.rst index d26a42c5c2..6b5eefb3c0 100644 --- a/doc/source/reference/pragma_def.rst +++ b/doc/source/reference/pragma_def.rst @@ -38,7 +38,7 @@ pragma directives may not be set and then unset within the same file. .. attr:: implied-branches - This is a list of regular expressions, just as + This is a list of :ref:`regular expressions `, just as :attr:`job.branches`, which may be used to supply the value of the implied branch matcher for all jobs and project-templates in a file. diff --git a/doc/source/reference/tenants.rst b/doc/source/reference/tenants.rst index d05154dd02..8e8d5f070d 100644 --- a/doc/source/reference/tenants.rst +++ b/doc/source/reference/tenants.rst @@ -305,18 +305,18 @@ configuration. Some examples of tenant definitions are: .. attr:: allowed-labels :default: [] - The list of labels (as strings or regular expressions) a tenant - can use in a job's nodeset. When set, this setting can be used - to restrict what labels a tenant can use. Without this setting, - the tenant can use any labels. + The list of labels (as strings or :ref:`regular expressions `) + a tenant can use in a job's nodeset. When set, this setting can + be used to restrict what labels a tenant can use. Without this + setting, the tenant can use any labels. .. attr:: disallowed-labels :default: [] - The list of labels (as strings or regular expressions) a tenant - is forbidden to use in a job's nodeset. When set, this setting - can be used to restrict what labels a tenant can use. Without - this setting, the tenant can use any labels permitted by + The list of labels (as strings or :ref:`regular expressions `) + a tenant is forbidden to use in a job's nodeset. When set, this + setting can be used to restrict what labels a tenant can use. + Without this setting, the tenant can use any labels permitted by :attr:`tenant.allowed-labels`. This check is applied after the check for `allowed-labels` and may therefore be used to further restrict the set of permitted labels.