Merge "Add more docs about pipelines"

2 files changed, 72 insertions, 9 deletions

diff --git a/doc/source/reference/glossary.rst b/doc/source/reference/glossary.rst
index 994fdf2fd..536c80034 100644
--- a/doc/source/reference/glossary.rst
+++ b/doc/source/reference/glossary.rst
@@ -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
diff --git a/doc/source/reference/pipeline_def.rst b/doc/source/reference/pipeline_def.rst
index 940758ba3..e2c2d9587 100644
--- a/doc/source/reference/pipeline_def.rst
+++ b/doc/source/reference/pipeline_def.rst
@@ -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