1==========
2Parameters
3==========
4
5Task-graph generation takes a collection of parameters as input, in the form of
6a JSON or YAML file.
7
8During decision-task processing, some of these parameters are supplied on the
9command line or by environment variables.  The decision task helpfully produces
10a full parameters file as one of its output artifacts.  The other ``mach
11taskgraph`` commands can take this file as input.  This can be very helpful
12when working on a change to the task graph.
13
14When experimenting with local runs of the task-graph generation, it is always
15best to find a recent decision task's ``parameters.yml`` file, and modify that
16file if necessary, rather than starting from scratch.  This ensures you have a
17complete set of parameters.
18
19The properties of the parameters object are described here, divided roughly by
20topic.
21
22Push Information
23----------------
24
25``base_repository``
26   The repository from which to do an initial clone, utilizing any available
27   caching.
28
29``head_repository``
30   The repository containing the changeset to be built.  This may differ from
31   ``base_repository`` in cases where ``base_repository`` is likely to be cached
32   and only a few additional commits are needed from ``head_repository``.
33
34``head_rev``
35   The revision to check out; this can be a short revision string
36
37``head_ref``
38   For Mercurial repositories, this is the same as ``head_rev``.  For
39   git repositories, which do not allow pulling explicit revisions, this gives
40   the symbolic ref containing ``head_rev`` that should be pulled from
41   ``head_repository``.
42
43``owner``
44   Email address indicating the person who made the push.  Note that this
45   value may be forged and *must not* be relied on for authentication.
46
47``message``
48   The try syntax in the commit message, if any.
49
50``pushlog_id``
51   The ID from the ``hg.mozilla.org`` pushlog
52
53``pushdate``
54   The timestamp of the push to the repository that triggered this decision
55   task.  Expressed as an integer seconds since the UNIX epoch.
56
57``hg_branch``
58  The mercurial branch where the revision lives in.
59
60``build_date``
61   The timestamp of the build date. Defaults to ``pushdate`` and falls back to present time of
62   taskgraph invocation. Expressed as an integer seconds since the UNIX epoch.
63
64``moz_build_date``
65   A formatted timestamp of ``build_date``. Expressed as a string with the following
66   format: %Y%m%d%H%M%S
67
68``tasks_for``
69   The ``tasks_for`` value used to generate the decision task.
70
71Tree Information
72----------------
73
74``project``
75   Another name for what may otherwise be called tree or branch or
76   repository.  This is the unqualified name, such as ``mozilla-central`` or
77   ``cedar``.
78
79``level``
80   The `SCM level
81   <https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/>`_
82   associated with this tree.  This dictates the names of resources used in the
83   generated tasks, and those tasks will fail if it is incorrect.
84
85Try Configuration
86-----------------
87
88``try_mode``
89    The mode in which a try push is operating.  This can be one of
90    ``"try_task_config"``, ``"try_option_syntax"``, ``"try_select"`` or ``None`` meaning no try
91    input was provided.
92
93    ``"try_select"`` is used by ``mach try fuzzy`` to build a list of tasks to select from.
94
95``try_options``
96    The arguments given as try syntax (as a dictionary), or ``None`` if
97    ``try_mode`` is not ``try_option_syntax``.
98
99``try_task_config``
100    The contents of the ``try_task_config.json`` file, or ``None`` if
101    ``try_mode`` is not ``try_task_config``.
102
103Target Set
104----------
105
106The "target set" is the set of task labels which must be included in a task
107graph.  The task graph generation process will include any tasks required by
108those in the target set, recursively.  In a decision task, this set can be
109specified programmatically using one of a variety of methods (e.g., parsing try
110syntax or reading a project-specific configuration file).
111
112``filters``
113    List of filter functions (from ``taskcluster/taskgraph/filter_tasks.py``) to
114    apply. This is usually defined internally, as filters are typically
115    global.
116
117``target_tasks_method``
118    The method to use to determine the target task set.  This is the suffix of
119    one of the functions in ``taskcluster/taskgraph/target_tasks.py``.
120
121``release_history``
122   History of recent releases by platform and locale, used when generating
123   partial updates for nightly releases.
124   Suitable contents can be generated with ``mach release-history``,
125   which will print to the console by default.
126
127Optimization
128------------
129
130``optimize_target_tasks``
131    If true, then target tasks are eligible for optimization.
132
133``do_not_optimize``
134   Specify tasks to not optimize out of the graph. This is a list of labels.
135   Any tasks in the graph matching one of the labels will not be optimized out
136   of the graph.
137
138``existing_tasks``
139   Specify tasks to optimize out of the graph. This is a dictionary of label to taskId.
140   Any tasks in the graph matching one of the labels will use the previously-run
141   taskId rather than submitting a new task.
142
143Release Promotion
144-----------------
145
146``build_number``
147   Specify the release promotion build number.
148
149``version``
150   Specify the version for release tasks.
151
152``app_version``
153   Specify the application version for release tasks. For releases, this is often a less specific version number than ``version``.
154
155``next_version``
156   Specify the next version for version bump tasks.
157
158``release_type``
159   The type of release being promoted. One of "nightly", "beta", "esr60", "release-rc", or "release".
160
161``release_eta``
162   The time and date when a release is scheduled to live. This value is passed to Balrog.
163
164``release_enable_partners``
165   Boolean which controls repacking vanilla Firefox builds for partners.
166
167``release_partners``
168   List of partners to repack. A null value defaults to all.
169
170``release_partner_config``
171   Configuration for partner repacks.
172
173``release_partner_build_number``
174   The build number for partner repacks. We sometimes have multiple partner build numbers per release build number; this parameter lets us bump them independently. Defaults to 1.
175
176``release_enable_emefree``
177   Boolean which controls repacking vanilla Firefox builds into EME-free builds.
178
179``release_product``
180   The product that is being released.
181
182``required_signoffs``
183   A list of signoffs that are required for this release promotion flavor. If specified, and if the corresponding `signoff_urls` url isn't specified, tasks that require these signoffs will not be scheduled.
184
185``signoff_urls``
186   A dictionary of signoff keys to url values. These are the urls marking the corresponding ``required_signoffs`` as signed off.
187
188Comm Push Information
189---------------------
190
191These parameters correspond to the repository and revision of the comm-central
192repository to checkout. Their meaning is the same as the corresponding
193parameters for the gecko repository above. They are optional, but if any of
194them are specified, they must all be specified.
195
196``comm_base_repository``
197``comm_head_repository``
198``comm_head_rev``
199``comm_head_ref``
200