Zuul v3: clarify stable branches
This brings the migration docs inline with the recommendations for the improved stable branch handling in Zuul. Change-Id: I2b150ccf7e712ddfaf9ab61a20e986630ce94501
This commit is contained in:
parent
2fefd0932b
commit
e60f8b436e
|
@ -183,16 +183,16 @@ allow us to express when a job should run in a human-friendly manner.
|
|||
<https://docs.openstack.org/infra/zuul/feature/zuulv3/user/config.html#job>`_
|
||||
|
||||
Job definitions may appear more than once in the Zuul configuration.
|
||||
We call the first instance the *reference* definition, and subsequent
|
||||
definitions *variants*. Job definitions have several fields, such as
|
||||
``branches`` and ``files``, which act as *matchers* to determine
|
||||
whether the job is applicable to a change. When Zuul runs a job, it
|
||||
builds up a new job definition with all of the matching variants
|
||||
applied. Later variants can override settings on earlier definitions,
|
||||
but any settings not overridden will be present as well.
|
||||
We call these multiple definitions *variants*. Job definitions have
|
||||
several fields, such as ``branches`` and ``files``, which act as
|
||||
*matchers* to determine whether the job is applicable to a change.
|
||||
When Zuul runs a job, it builds up a new job definition with all of
|
||||
the matching variants applied. Later variants can override settings
|
||||
on earlier definitions, but any settings not overridden will be
|
||||
present as well.
|
||||
|
||||
For example, consider this simple reference job definition for a job
|
||||
named ``fedstack``:
|
||||
For example, consider this simple job definition for a job named
|
||||
``fedstack``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
@ -235,10 +235,9 @@ this:
|
|||
We call the highlighted portion the ``project-pipeline`` definition.
|
||||
That says "run the fedstack job on changes to the cloudycloud project
|
||||
in the check pipeline". A change to the master branch of cloudycloud
|
||||
will run the job described in the reference definition above. A
|
||||
change on the stable/pike branch will combine *both* the reference
|
||||
definition and the variant and use the new merged definition when
|
||||
running the job.
|
||||
will run the job described in the first definition above. A change on
|
||||
the stable/pike branch will combine *both* variants and use the new
|
||||
merged definition when running the job.
|
||||
|
||||
If we want to change how the job is run *only* for the cloudycloud
|
||||
project, we can alter the project-pipeline definition to specify a
|
||||
|
@ -261,15 +260,16 @@ This variant is combined with all other matching variants to indicate
|
|||
that all fedstack jobs run on cloudycloud are non-voting, and
|
||||
additionally, stable/pike jobs run on fedora-25 instead of fedora-26.
|
||||
|
||||
As long as at least one variant matches a change, the job will run; a
|
||||
variant can't be used to "undo" an earlier matching variant.
|
||||
|
||||
One final note about variants: in some cases Zuul attaches an implied
|
||||
branch matcher to job definitions. The rules are `tricky
|
||||
<https://docs.openstack.org/infra/zuul/feature/zuulv3/user/config.html#attr-job.branches>`_,
|
||||
but in general, jobs and variants defined in the master branch of a
|
||||
project will apply to all branches, and any further variants defined
|
||||
in other branches get an implied branch matcher of their current
|
||||
branch. This makes it so that we can branch a project from master
|
||||
along with all of its job definitions, and jobs will continue to work
|
||||
as expected.
|
||||
but in general, jobs defined in a multi-branch project get an implied
|
||||
branch matcher of their current branch. This makes it so that we can
|
||||
branch a project from master along with all of its job definitions,
|
||||
and jobs will continue to work as expected.
|
||||
|
||||
I Write Jobs, How Does Zuul v3 Actually Work?
|
||||
=============================================
|
||||
|
@ -754,22 +754,18 @@ At your earliest convenience, for every job specific to your project:
|
|||
Stable Branches
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
If your project has stable branches, you will also need to add a
|
||||
``.zuul.yaml`` file to each stable branch. The Zuul config on stable
|
||||
branches doesn't need everything on the master branch -- the jobs
|
||||
defined in the master branch will be available in any branch. But it
|
||||
does at least need a ``project`` stanza. When a project stanza is
|
||||
added to an in-repo project definition, unless branches are explicitly
|
||||
specified for the jobs in the project stanza, Zuul will assume the
|
||||
jobs listed should only be run on the current branch.
|
||||
|
||||
To make sure your jobs run on all the right branches, just copy the
|
||||
``project`` stanza from the master branch. If there are any jobs
|
||||
which should not run on any particular stable branch, omit them; and
|
||||
if there are jobs which should only run on that branch, add them.
|
||||
|
||||
If you have playbooks or roles included on the master branch, backport
|
||||
these as well.
|
||||
If your project has stable branches, you should also add a
|
||||
``.zuul.yaml`` file (with job and project definitions -- just as on
|
||||
master) and any playbooks to each stable branch. Zuul will
|
||||
automatically add branch matchers for the current branch to any jobs
|
||||
defined on a multi-branch project. Jobs defined in a stable branch
|
||||
will therefore only apply to changes on the stable branch, and
|
||||
likewise master. Backporting these changes is a little more work now
|
||||
during the transition from Zuul v2 to v3, but when we make the next
|
||||
stable branch from master, no extra would should be required -- the
|
||||
new branch will already contain all the right content, and
|
||||
configuration on both the master and stable branches will be able to
|
||||
diverge naturally.
|
||||
|
||||
Reworking Legacy Jobs to be v3 Native
|
||||
-------------------------------------
|
||||
|
|
Loading…
Reference in New Issue