Browse Source

Merge "Document practical use case for variable defaults"

tags/2.5.0
Zuul 10 months ago
parent
commit
dca93849ed
1 changed files with 137 additions and 8 deletions
  1. 137
    8
      doc/source/definition.rst

+ 137
- 8
doc/source/definition.rst View File

@@ -83,6 +83,7 @@ support such use cases in addition to simplifying referencing
83 83
 templates when the name contains the more complex substitution with
84 84
 default values.
85 85
 
86
+.. _default-values:
86 87
 
87 88
 Default Values for Template Variables
88 89
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -92,8 +93,79 @@ substituted, but where in most cases the same or no value is needed,
92 93
 it is possible to specify defaults for the variables within the
93 94
 templates themselves.
94 95
 
95
-This can be used to provide common settings for particular templates.
96
-For example:
96
+There are 2 ways JJB allows us to define defaults for a parameter in a
97
+job-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
+
168
+More complex example:
97 169
 
98 170
 .. literalinclude::
99 171
     /../../tests/yamlparser/fixtures/template_default_variables.yaml
@@ -503,14 +575,71 @@ and replace them with the empty string instead.
503 575
 
504 576
 .. tip::
505 577
 
506
-   Defaults for variables can be set by using the ``|`` character
507
-   ``{var|default_value}``. This is useful if we want to allow users of the
508
-   job-template to not have to pass a setting if there is a common default for
509
-   it.
578
+   Refer to :ref:`default-values` for details on setting variable defaults.
579
+
580
+Variable Inheritence
581
+^^^^^^^^^^^^^^^^^^^^
582
+
583
+It is possible in JJB to define defaults for variables at different levels such
584
+that it is possible for users of job-templates to override variables defined
585
+in the job-template.
586
+
587
+Variable priorities for each definition type are as follows:
588
+
589
+#. job-group
590
+#. project
591
+#. job-template
592
+#. defaults
593
+
594
+From this list we can immediately see that if we want to make variables in
595
+job-templates override-able then using defaults configuration is useless as it
596
+has the lowest precedence when JJB is deciding where to pull from.
597
+
598
+On the other side of the spectrum, job-groups has the highest precedence. Which
599
+unfortunately means if we define a variable in a job-group with the intention
600
+of overriding it at the project level then we are out of luck. For this reason
601
+avoid setting variables in job-groups unless we want to enforce a setting for a
602
+set of jobs and prevent projects from overriding it.
603
+
604
+Declaring variable defaults
605
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
606
+
607
+Refer to :ref:`default-values` for details on how to declare variable defaults.
608
+
609
+Overriding job-template variables
610
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
611
+
612
+When 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
+
624
+This is the standard way that most folks use and it will set ``branch: master``
625
+for every job-template in the list. However sometimes we may want to provide an
626
+alternative value for a specific job in the list. In this case the more
627
+specific 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:
640
+In this case the verify job will get the value **master** but the merge job
641
+will instead get the branch value **production**.
512 642
 
513
-   .. literalinclude:: /../../tests/yamlparser/fixtures/variable_defaults.yaml
514 643
 
515 644
 Yaml Anchors & Aliases
516 645
 ^^^^^^^^^^^^^^^^^^^^^^

Loading…
Cancel
Save