Combine branch templates and pipeline branch matchers
In a situation where a projec-template is defined on multiple branches
and then used by a project on multiple branches, the behavior was not
as one might expect.
Currently, assuming no explicit branch matchers are in play, all the
jobs listed in the project-template will get implied branch matchers
attached. So the resulting template looks like
- job @ master
- job @ stable/newton
- job @ stable/ocata
Then when that template is applied to the project, since the jobs within
already have branch matchers, the implied branch matcher for the project
pipeline definition is not applied. When the template is added to the
project on the ocata branch, all 3 of those jobs are added to the project,
and when it is added on the newton branch, all 3 jobs are added to the
project again. That's invisible to the user, until they attempt to remove
the template from one of the branches. Because the other branches still
add the template, which contains all the jobs, they still run.
To correct this, either replace the branch matcher obtained from the job
in the project template (if it is a simple match of a single branch), or
combine it using a boolean "and" (if it is something more complex) with a
branch matcher for the project definition. When the above template is added
to a project on the newton branch, only the following job will be added to
the project-pipeline:
- job @ stable/newton
When the template is added on the ocata branch, likewise only the ocata job
will be added.
If, instead, the project template had an explicit branch matcher, the
resulting template might be:
- job @ ^(?!stable/diablo).*$
After adding that to the project on the newton branch, the resulting project
pipeline would be:
- job @ { ^(?!stable/diablo).*$ AND stable/newton }
Ensuring that since the template was only added to the project on newton,
its jobs only run on newton changes.
Change-Id: I1969d588bc47b8ab5a54a885a68f98178b16b9d5
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index fa874a9..3ea20ab 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -658,8 +658,17 @@
* In the case of a job variant defined within a
:ref:`project-template`, if no branch specifier appears, the
- implied branch specifier for the :ref:`project` definition which
- uses the project-template will be used.
+ 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