taskcluster/docs/try.rst

   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 three methods for scheduling a task on try: legacy try option syntax,
  17 try task config, and an empty try.
  18
  19 Try Option Syntax
  20 :::::::::::::::::
  21
  22 The first, older method is a command line string called ``try syntax`` which is passed
  23 into the decision task via the commit message. The resulting commit is then
  24 pushed to the https://hg.mozilla.org/try repository.  An example try syntax
  25 might look like:
  26
  27 .. parsed-literal::
  28
  29     try: -b o -p linux64 -u mochitest-1 -t none
  30
  31 This gets parsed by ``taskgraph.try_option_syntax:TryOptionSyntax`` and returns
  32 a list of matching task labels. For more information see the
  33 `TryServer wiki page <https://wiki.mozilla.org/Try>`_.
  34
  35 Try Task Config
  36 :::::::::::::::
  37
  38 The second, more modern method specifies exactly the tasks to run.  That list
  39 of tasks is usually generated locally with some :doc:`local tool </tools/try/selectors/fuzzy>`
  40 and attached to the commit pushed to the try repository. This gives
  41 finer control over exactly what runs and enables growth of an
  42 ecosystem of tooling appropriate to varied circumstances.
  43
  44 Implementation
  45 ,,,,,,,,,,,,,,
  46
  47 This method uses a checked-in file called ``try_task_config.json`` which lives
  48 at 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
  66 Very simply, this will run any task label that gets passed in as well as their
  67 dependencies. While it is possible to manually commit this file and push to
  68 try, it is mainly meant to be a generation target for various :ref:`try server <Pushing to Try>`
  69 choosers.  For example:
  70
  71 .. parsed-literal::
  72
  73     $ ./mach try fuzzy
  74
  75 A list of all possible task labels can be obtained by running:
  76
  77 .. parsed-literal::
  78
  79     $ ./mach taskgraph tasks
  80
  81 A list of task labels relevant to a tree (defaults to mozilla-central) can be
  82 obtained with:
  83
  84 .. parsed-literal::
  85
  86     $ ./mach taskgraph target
  87
  88 Modifying Tasks in a Try Push
  89 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
  90
  91 It's possible to alter the definition of a task by defining additional
  92 configuration in ``try_task_config.json``. For example, to set an environment
  93 variable 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
 105 The allowed configs are defined in :py:obj:`taskgraph.decision.try_task_config_schema`.
 106 The values will be available to all transforms, so how each config applies will
 107 vary wildly from one context to the next. Some (such as ``env``) will affect
 108 all 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
 111 Empty Try
 112 :::::::::
 113
 114 If there is no try syntax or ``try_task_config.json``, the ``try_mode``
 115 parameter is None and no tasks are selected to run.  The resulting push will
 116 only have a decision task, but one with an "add jobs" action that can be used
 117 to add the desired jobs to the try push.
 118
 119
 120 Complex Configuration
 121 :::::::::::::::::::::
 122
 123 If you need more control over the build configuration,
 124 (:doc:`staging releases </tools/try/selectors/release>`, for example),
 125 you can directly specify :doc:`parameters <parameters>`
 126 to 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
 139 This format can express a superset of the version 1 format, as the
 140 version one configuration is equivalent to the following version 2
 141 config.
 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/