Expose final job attribute
Exposing the final job attribute make it possible to directly
configure a job as final.
Prohibit inheritance with final
This is no longer automatically set based on auth inheritance, so
now only exists as an attribute for a user to set explicitly.
The word "final" has a pretty specifig meaning for software developers
at least, so let's err on the side of safety there to provide folks
with the least surprise.
Also document it.
Change-Id: Ibeb7fd0ec1ce4f053a16066ccc8c2dd93c6f659e
Co-Authored-By: James E. Blair <jeblair@redhat.com>
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index 7ccce28..4898e17 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -438,7 +438,7 @@
jobs on the system should have, progressing through stages of
specialization before arriving at a particular job. A job may inherit
from any other job in any project (however, if the other job is marked
-as ``final``, some attributes may not be overidden).
+as :attr:`job.final`, jobs may not inherit from it).
A job with no parent is called a *base job* and may only be defined in
a :term:`config-project`. Every other job must have a parent, and so
@@ -452,7 +452,8 @@
These may have different selection criteria which indicate to Zuul
that, for instance, the job should behave differently on a different
git branch. Unlike inheritance, all job variants must be defined in
-the same project.
+the same project. Some attributes of jobs marked :attr:`job.final`
+may not be overidden
When Zuul decides to run a job, it performs a process known as
freezing the job. Because any number of job variants may be
@@ -529,6 +530,14 @@
to auto-document Zuul jobs (in which case it is interpreted as
ReStructuredText.
+ .. attr:: final
+ :default: false
+
+ To prevent other jobs from inheriting from this job, and also to
+ prevent changing execution-related attributes when this job is
+ specified in a project's pipeline, set this attribute to
+ ``true``.
+
.. attr:: success-message
:default: SUCCESS