1Try
2===
3
4"Try" is a way to "try out" a proposed change safely before review, without
5officially landing it.  This functionality has been around for a *long* time in
6various forms, and can sometimes show its age.
7
8Access to "push to try" is typically available to a much larger group of
9developers than those who can land changes in integration and release branches.
10Specifically, try pushes are allowed for anyone with `SCM Level`_ 1, while
11integration branches are at SCM level 3.
12
13Scheduling a Task on Try
14------------------------
15
16There are three methods for scheduling a task on try: legacy try option syntax,
17try task config, and an empty try.
18
19Try Option Syntax
20:::::::::::::::::
21
22The first, older method is a command line string called ``try syntax`` which is passed
23into the decision task via the commit message. The resulting commit is then
24pushed to the https://hg.mozilla.org/try repository.  An example try syntax
25might look like:
26
27.. parsed-literal::
28
29    try: -b o -p linux64 -u mochitest-1 -t none
30
31This gets parsed by ``taskgraph.try_option_syntax:TryOptionSyntax`` and returns
32a list of matching task labels. For more information see the
33`TryServer wiki page <https://wiki.mozilla.org/Try>`_.
34
35Try Task Config
36:::::::::::::::
37
38The second, more modern method specifies exactly the tasks to run.  That list
39of tasks is usually generated locally with some :doc:`local tool </tools/try/selectors/fuzzy>`
40and attached to the commit pushed to the try repository. This gives
41finer control over exactly what runs and enables growth of an
42ecosystem of tooling appropriate to varied circumstances.
43
44Implementation
45,,,,,,,,,,,,,,
46
47This method uses a checked-in file called ``try_task_config.json`` which lives
48at the root of the source dir. The JSON object in this file contains a
49``tasks`` key giving the labels of the tasks to run.  For example, the
50``try_task_config.json`` file might look like:
51
52.. parsed-literal::
53
54    {
55      "version": 1,
56      "tasks": [
57        "test-windows10-64/opt-web-platform-tests-12",
58        "test-windows7-32/opt-reftest-1",
59        "test-windows7-32/opt-reftest-2",
60        "test-windows7-32/opt-reftest-3",
61        "build-linux64/debug",
62        "source-test-mozlint-eslint"
63      ]
64    }
65
66Very simply, this will run any task label that gets passed in as well as their
67dependencies. While it is possible to manually commit this file and push to
68try, it is mainly meant to be a generation target for various :doc:`tryselect </tools/try>`
69choosers.  For example:
70
71.. parsed-literal::
72
73    $ ./mach try fuzzy
74
75A list of all possible task labels can be obtained by running:
76
77.. parsed-literal::
78
79    $ ./mach taskgraph tasks
80
81A list of task labels relevant to a tree (defaults to mozilla-central) can be
82obtained with:
83
84.. parsed-literal::
85
86    $ ./mach taskgraph target
87
88Modifying Tasks in a Try Push
89,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
90
91It's possible to alter the definition of a task with templates. Templates are
92`JSON-e`_ files that live in the `taskgraph module`_. Templates can be specified
93from the ``try_task_config.json`` like this:
94
95.. parsed-literal::
96
97    {
98      "version": 1,
99      "tasks": [...],
100      "templates": {
101        artifact: {"enabled": 1}
102      }
103    }
104
105Each key in the templates object denotes a new template to apply, and the value
106denotes extra context to use while rendering. When specified, a template will
107be applied to every task no matter what. If the template should only be applied
108to certain kinds of tasks, this needs to be specified in the template itself
109using JSON-e `condition statements`_.
110
111The context available to the JSON-e render contains attributes from the
112:py:class:`taskgraph.task.Task` class. It looks like this:
113
114.. parsed-literal::
115
116    {
117      "attributes": task.attributes,
118      "kind": task.kind,
119      "label": task.label,
120      "target_tasks": [<tasks from try_task_config.json>],
121      "task": task.task,
122      "taskId": task.task_id,
123      "input": ...
124    }
125
126The ``input`` context can be any arbitrary value or object. What it contains
127depends on each specific template. Templates must return objects that have have
128either ``attributes`` or ``task`` as a top level key. All other top level keys
129will be ignored. See the `existing templates`_ for examples.
130
131Empty Try
132:::::::::
133
134If there is no try syntax or ``try_task_config.json``, the ``try_mode``
135parameter is None and no tasks are selected to run.  The resulting push will
136only have a decision task, but one with an "add jobs" action that can be used
137to add the desired jobs to the try push.
138
139
140Complex Configuration
141:::::::::::::::::::::
142
143If you need more control over the build configuration,
144(:doc:`staging releases </tools/try/selectors/release>`, for example),
145you can directly specify :doc:`parameters <parameters>`
146to override from the ``try_task_config.json`` like this:
147
148.. parsed-literal::
149
150   {
151       "version": 2,
152       "parameters": {
153           "optimize_target_tasks": true,
154           "release_type": "beta",
155           "target_tasks_method": "staging_release_builds"
156       }
157   }
158
159This format can express a superset of the version 1 format, as the
160version one configuration is equivalent to the following version 2
161config.
162
163.. parsed-literal::
164
165   {
166       "version": 2,
167       "parameters": {
168           "try_task_config": {...},
169           "try_mode": "try_task_config",
170       }
171   }
172
173.. _JSON-e: https://taskcluster.github.io/json-e/
174.. _taskgraph module: https://dxr.mozilla.org/mozilla-central/source/taskcluster/taskgraph/templates
175.. _condition statements: https://taskcluster.github.io/json-e/#%60$if%60%20-%20%60then%60%20-%20%60else%60
176.. _existing templates: https://dxr.mozilla.org/mozilla-central/source/taskcluster/taskgraph/templates
177.. _SCM Level: https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/
178
179
180