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