try.rst (4187B)
1 Try 2 === 3 4 "Try" is a way to "try out" a proposed change safely before review, without 5 officially landing it. This functionality has been around for a *long* time in 6 various forms, and can sometimes show its age. 7 8 Access to "push to try" is typically available to a much larger group of 9 developers than those who can land changes in integration and release branches. 10 Specifically, try pushes are allowed for anyone with `SCM Level`_ 1, while 11 integration branches are at SCM level 3. 12 13 Scheduling a Task on Try 14 ------------------------ 15 16 There are two methods for scheduling a task on try: try task config, and an empty try. 17 18 Try Task Config 19 ::::::::::::::: 20 21 The second, more modern method specifies exactly the tasks to run. That list 22 of tasks is usually generated locally with some :doc:`local tool </tools/try/selectors/fuzzy>` 23 and attached to the commit pushed to the try repository. This gives 24 finer control over exactly what runs and enables growth of an 25 ecosystem of tooling appropriate to varied circumstances. 26 27 Implementation 28 ,,,,,,,,,,,,,, 29 30 This method uses a checked-in file called ``try_task_config.json`` which lives 31 at the root of the source dir. The JSON object in this file contains a 32 ``tasks`` key giving the labels of the tasks to run. For example, the 33 ``try_task_config.json`` file might look like: 34 35 .. parsed-literal:: 36 37 { 38 "version": 1, 39 "tasks": [ 40 "test-windows10-64/opt-web-platform-tests-12", 41 "test-windows7-32/opt-reftest-1", 42 "test-windows7-32/opt-reftest-2", 43 "test-windows7-32/opt-reftest-3", 44 "build-linux64/debug", 45 "source-test-mozlint-eslint" 46 ] 47 } 48 49 Very simply, this will run any task label that gets passed in as well as their 50 dependencies. While it is possible to manually commit this file and push to 51 try, it is mainly meant to be a generation target for various :ref:`try server <Pushing to Try>` 52 choosers. For example: 53 54 .. parsed-literal:: 55 56 $ ./mach try fuzzy 57 58 A list of all possible task labels can be obtained by running: 59 60 .. parsed-literal:: 61 62 $ ./mach taskgraph tasks 63 64 A list of task labels relevant to a tree (defaults to mozilla-central) can be 65 obtained with: 66 67 .. parsed-literal:: 68 69 $ ./mach taskgraph target 70 71 Modifying Tasks in a Try Push 72 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 73 74 It's possible to alter the definition of a task by defining additional 75 configuration in ``try_task_config.json``. For example, to set an environment 76 variable in all tasks, you can add: 77 78 .. parsed-literal:: 79 80 { 81 "version": 1, 82 "tasks": [...], 83 "env": { 84 "FOO": "bar" 85 } 86 } 87 88 The allowed configs are defined in :py:obj:`taskgraph.decision.try_task_config_schema`. 89 The values will be available to all transforms, so how each config applies will 90 vary wildly from one context to the next. Some (such as ``env``) will affect 91 all tasks in the graph. Others might only affect certain kinds of task. The 92 ``use-artifact-builds`` config only applies to build tasks for instance. 93 94 Empty Try 95 ::::::::: 96 97 If there is no try syntax or ``try_task_config.json``, the ``try_mode`` 98 parameter is None and no tasks are selected to run. The resulting push will 99 only have a decision task, but one with an "add jobs" action that can be used 100 to add the desired jobs to the try push. 101 102 103 Complex Configuration 104 ::::::::::::::::::::: 105 106 If you need more control over the build configuration, 107 (:doc:`staging releases </tools/try/selectors/release>`, for example), 108 you can directly specify :doc:`parameters <parameters>` 109 to override from the ``try_task_config.json`` like this: 110 111 .. parsed-literal:: 112 113 { 114 "version": 2, 115 "parameters": { 116 "optimize_target_tasks": true, 117 "release_type": "beta", 118 "target_tasks_method": "staging_release_builds" 119 } 120 } 121 122 This format can express a superset of the version 1 format, as the 123 version one configuration is equivalent to the following version 2 124 config. 125 126 .. parsed-literal:: 127 128 { 129 "version": 2, 130 "parameters": { 131 "try_task_config": {...}, 132 "try_mode": "try_task_config", 133 } 134 } 135 136 .. _SCM Level: https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/