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 :ref:`try server <Pushing to 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