zuul
/
zuul
Code Issues Proposed changes

Add more docs about pipelines 

This adds more glossary terms for pipelines and links to those from
the pipeline feature matrix table.

Change-Id: Ibf588c05d984093cf8cceee7085e1051afa0982d
This commit is contained in:
James E. Blair 2020-04-28 15:16:39 -07:00
parent 22640baef4
commit 3269edb132
2 changed files with 72 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
doc/source/reference/glossary.rst
View File

@ -66,7 +66,10 @@ Glossary
yet seen any human review, so care must be taken in selecting
the kinds of jobs to run, and what resources will be available
to them in order to avoid misuse of the system or credential
compromise.
compromise. It usually has an :value:`independent
<pipeline.manager.independent>` pipeline manager since the final
sequence of changes to merge is not generally known at the time
of upload.
config-project
@ -94,6 +97,20 @@ Glossary
incorporate any cross-project dependencies into the context
for the change declaring that dependency relationship.
deploy
By convention, the name of a continuous-deployment pipeline.
Such a pipeline typically interacts with production systems
rather than ephemeral test nodes. By triggering on merge events
the results of deployment can be reported back to the
originating change. The :value:`serial
<pipeline.manager.serial>` pipeline manager, is recommended if
multiple repositories are involved and only some jobs (based on
file matchers) will be run for each change. If a single repo is
involved and all deployment jobs run on every change merged,
then :value:`supercedent <pipeline.manager.supercedent>` may be
a better fit.
executor
The component of Zuul responsible for executing a sandboxed
@ -224,6 +241,21 @@ Glossary
of reusing the same sets of jobs in the same pipelines across
multiple projects.
promote
By convention, the name of a pipeline which uploads previously
built artifacts. These artifacts should be constructed in a
:term:`gate` pipeline and uploaded to a temporary location.
When all of the jobs in the gate pipeline succeed, the change
will be merged and may then be enqueued into a promote pipeline.
Jobs running in this pipeline do so with the understanding that
since the change merged as it was tested in the gate, any
artifacts created at that time are now safe to promote to
production. It is a good choice to use a :value:`supercedent
<pipeline.manager.supercedent>` pipeline manager so that if many
changes merge in rapid sequence, Zuul may skip promoting all but
the latest artifact to production.
provided artifact
A named artifact which builds of a job are expected to
@ -232,6 +264,30 @@ Glossary
same name, allowing these relationships to be defined
independent of the specific jobs which provide them.
post
By convention, the name of a pipeline which runs after a branch
is updated. By triggering on a branch update (rather than a
merge) event, jobs in this pipeline may run with the final git
state after the merge (including any merge commits generated by
the upstream code review system). This is important when
building some artifacts in order that the exact commit ids are
present in the git repo. The downside to this approach is that
jobs in this pipeline run without any connection to the
underlying changes which created the commits. If only the
latest updates to a branch matter, then the :value:`supercedent
<pipeline.manager.supercedent>` pipeline manager is recommended;
otherwise :value:`independent <pipeline.manager.independent>`
may be a better choice. See also :term:`tag` and
:term:`release`.
release
By convention, the name of a pipeline which runs after a
release-formatted tag is updated. Other than the matching ref,
this is typically constructed the same as a :term:`post`
pipeline. See also :term:`tag`.
reporter
A reporter is a :ref:`pipeline attribute <reporters>` which
@ -276,6 +332,13 @@ Glossary
queue items to no longer include it in their respective
contexts.
tag
By convention, the name of a pipeline which runs after a tag is
updated. Other than the matching ref, this is typically
constructed the same as a :term:`post` pipeline. See also
:term:`release`.
tenant
A set of projects on which Zuul should operate. Configuration

16
doc/source/reference/pipeline_def.rst
View File

@ -67,14 +67,14 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
table summarizes their features; each is described in detail
below.
=========== ============ ===== ============= =========
Manager Dependencies Merge Shared Queues Window
=========== ============ ===== ============= =========
Independent No No No Unlimited
Dependent Yes Yes Yes Variable
Serial No No Yes 1
Supercedent No No Project-ref 1
=========== ============ ===== ============= =========
=========== ============================= ============ ===== ============= =========
Manager Use Case Dependencies Merge Shared Queues Window
=========== ============================= ============ ===== ============= =========
Independent :term:`check`, :term:`post` No No No Unlimited
Dependent :term:`gate` Yes Yes Yes Variable
Serial :term:`deploy` No No Yes 1
Supercedent :term:`post`, :term:`promote` No No Project-ref 1
=========== ============================= ============ ===== ============= =========
.. value:: independent