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 by defining additional
92configuration in ``try_task_config.json``. For example, to set an environment
93variable in all tasks, you can add:
94
95.. parsed-literal::
96
97    {
98      "version": 1,
99      "tasks": [...],
100      "env": {
101        "FOO": "bar"
102      }
103    }
104
105The allowed configs are defined in :py:obj:`taskgraph.decision.try_task_config_schema`.
106The values will be available to all transforms, so how each config applies will
107vary wildly from one context to the next. Some (such as ``env``) will affect
108all tasks in the graph. Others might only affect certain kinds of task. The
109``use-artifact-builds`` config only applies to build tasks for instance.
110
111Empty Try
112:::::::::
113
114If there is no try syntax or ``try_task_config.json``, the ``try_mode``
115parameter is None and no tasks are selected to run.  The resulting push will
116only have a decision task, but one with an "add jobs" action that can be used
117to add the desired jobs to the try push.
118
119
120Complex Configuration
121:::::::::::::::::::::
122
123If you need more control over the build configuration,
124(:doc:`staging releases </tools/try/selectors/release>`, for example),
125you can directly specify :doc:`parameters <parameters>`
126to override from the ``try_task_config.json`` like this:
127
128.. parsed-literal::
129
130   {
131       "version": 2,
132       "parameters": {
133           "optimize_target_tasks": true,
134           "release_type": "beta",
135           "target_tasks_method": "staging_release_builds"
136       }
137   }
138
139This format can express a superset of the version 1 format, as the
140version one configuration is equivalent to the following version 2
141config.
142
143.. parsed-literal::
144
145   {
146       "version": 2,
147       "parameters": {
148           "try_task_config": {...},
149           "try_mode": "try_task_config",
150       }
151   }
152
153.. _SCM Level: https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/
154