summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2018-09-16 18:51:24 +0000
committerGerrit Code Review <review@openstack.org>2018-09-16 18:51:24 +0000
commitdca93849edd718297592b96fcd10fa06c85aaa6d (patch)
tree628666fbf34f29ea939ec7bd7c1a894989ca0f3a
parentc32bb73d70048a6fac423025efe2ce5560d24282 (diff)
parentce040d8ad60cdc0f2a6ad1ee32d8228909e8a7d9 (diff)
Merge "Document practical use case for variable defaults"
-rw-r--r--doc/source/definition.rst145
1 files changed, 137 insertions, 8 deletions
diff --git a/doc/source/definition.rst b/doc/source/definition.rst
index 83c975a..029c944 100644
--- a/doc/source/definition.rst
+++ b/doc/source/definition.rst
@@ -83,6 +83,7 @@ support such use cases in addition to simplifying referencing
83templates when the name contains the more complex substitution with 83templates when the name contains the more complex substitution with
84default values. 84default values.
85 85
86.. _default-values:
86 87
87Default Values for Template Variables 88Default Values for Template Variables
88~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -92,8 +93,79 @@ substituted, but where in most cases the same or no value is needed,
92it is possible to specify defaults for the variables within the 93it is possible to specify defaults for the variables within the
93templates themselves. 94templates themselves.
94 95
95This can be used to provide common settings for particular templates. 96There are 2 ways JJB allows us to define defaults for a parameter in a
96For example: 97job-template.
98
99#. Defining the default variable value in the job-template itself
100
101 With this method we declare the default value of the variable in the
102 job-template itself just once. We can section off the job-template into
103 two sections like this:
104
105 .. code-block:: yaml
106
107 - job-template:
108 name: '{project-name}-verify'
109
110 #####################
111 # Variable Defaults #
112 #####################
113
114 branch: master
115
116 #####################
117 # Job Configuration #
118 #####################
119
120 parameters:
121 - string:
122 name: BRANCH
123 default: '{branch}'
124
125 scm:
126 - git:
127 refspec: 'refs/heads/{branch}'
128
129 In this case there is still two branch definitions for the job-template.
130 However we also provide the default value for the {branch} variable at the
131 top of the file. Just once. This will be the value that the job takes on if
132 it is not passed in by a project using the template.
133
134#. Using {var|default}
135
136 In this method we can define the default with the definition of the
137 variable. For example:
138
139 .. code-block:: yaml
140
141 - job-template:
142 name: '{project-name}-verify'
143 parameters:
144 - string:
145 name: BRANCH
146 default: '{branch|master}'
147
148 However where this method falls apart if we need to use the same JJB
149 variable in more than one place as we will have multiple places to define
150 the default value for the template. For example:
151
152 .. code-block:: yaml
153
154 - job-template:
155 name: '{project-name}-verify'
156 parameters:
157 - string:
158 name: BRANCH
159 default: '{branch|master}'
160
161 scm:
162 - git:
163 refspec: 'refs/heads/{branch|master}'
164
165 We can see in this case the ``{branch|master}`` variable is defined in two
166 places. Not ideal.
167
168More complex example:
97 169
98.. literalinclude:: 170.. literalinclude::
99 /../../tests/yamlparser/fixtures/template_default_variables.yaml 171 /../../tests/yamlparser/fixtures/template_default_variables.yaml
@@ -503,14 +575,71 @@ and replace them with the empty string instead.
503 575
504.. tip:: 576.. tip::
505 577
506 Defaults for variables can be set by using the ``|`` character 578 Refer to :ref:`default-values` for details on setting variable defaults.
507 ``{var|default_value}``. This is useful if we want to allow users of the 579
508 job-template to not have to pass a setting if there is a common default for 580Variable Inheritence
509 it. 581^^^^^^^^^^^^^^^^^^^^
582
583It is possible in JJB to define defaults for variables at different levels such
584that it is possible for users of job-templates to override variables defined
585in the job-template.
586
587Variable priorities for each definition type are as follows:
588
589#. job-group
590#. project
591#. job-template
592#. defaults
593
594From this list we can immediately see that if we want to make variables in
595job-templates override-able then using defaults configuration is useless as it
596has the lowest precedence when JJB is deciding where to pull from.
597
598On the other side of the spectrum, job-groups has the highest precedence. Which
599unfortunately means if we define a variable in a job-group with the intention
600of overriding it at the project level then we are out of luck. For this reason
601avoid setting variables in job-groups unless we want to enforce a setting for a
602set of jobs and prevent projects from overriding it.
603
604Declaring variable defaults
605~~~~~~~~~~~~~~~~~~~~~~~~~~~
606
607Refer to :ref:`default-values` for details on how to declare variable defaults.
608
609Overriding job-template variables
610~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
611
612When a project wants to use a job-template it can use override it as follows:
613
614.. code-block:: yaml
615
616 - project:
617 name: foo
618 jobs:
619 - '{project-name}-merge'
620 - '{project-name}-verify'
621
622 branch: master
623
624This is the standard way that most folks use and it will set ``branch: master``
625for every job-template in the list. However sometimes we may want to provide an
626alternative value for a specific job in the list. In this case the more
627specific declaration takes precendence:
628
629.. code-block:: yaml
630
631 - project:
632 name: foo
633 jobs:
634 - '{project-name}-merge':
635 branch: production
636 - '{project-name}-verify'
637
638 branch: master
510 639
511 Example: 640In this case the verify job will get the value **master** but the merge job
641will instead get the branch value **production**.
512 642
513 .. literalinclude:: /../../tests/yamlparser/fixtures/variable_defaults.yaml
514 643
515Yaml Anchors & Aliases 644Yaml Anchors & Aliases
516^^^^^^^^^^^^^^^^^^^^^^ 645^^^^^^^^^^^^^^^^^^^^^^