summaryrefslogtreecommitdiffstats
path: root/taskcluster/docs/try.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
commit6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch)
treea68f146d7fa01f0134297619fbe7e33db084e0aa /taskcluster/docs/try.rst
parentInitial commit. (diff)
downloadthunderbird-upstream.tar.xz
thunderbird-upstream.zip
Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--taskcluster/docs/try.rst153
1 files changed, 153 insertions, 0 deletions
diff --git a/taskcluster/docs/try.rst b/taskcluster/docs/try.rst
new file mode 100644
index 0000000000..5639cdb615
--- /dev/null
+++ b/taskcluster/docs/try.rst
@@ -0,0 +1,153 @@
+Try
+===
+
+"Try" is a way to "try out" a proposed change safely before review, without
+officially landing it. This functionality has been around for a *long* time in
+various forms, and can sometimes show its age.
+
+Access to "push to try" is typically available to a much larger group of
+developers than those who can land changes in integration and release branches.
+Specifically, try pushes are allowed for anyone with `SCM Level`_ 1, while
+integration branches are at SCM level 3.
+
+Scheduling a Task on Try
+------------------------
+
+There are three methods for scheduling a task on try: legacy try option syntax,
+try task config, and an empty try.
+
+Try Option Syntax
+:::::::::::::::::
+
+The first, older method is a command line string called ``try syntax`` which is passed
+into the decision task via the commit message. The resulting commit is then
+pushed to the https://hg.mozilla.org/try repository. An example try syntax
+might look like:
+
+.. parsed-literal::
+
+ try: -b o -p linux64 -u mochitest-1 -t none
+
+This gets parsed by ``taskgraph.try_option_syntax:TryOptionSyntax`` and returns
+a list of matching task labels. For more information see the
+`TryServer wiki page <https://wiki.mozilla.org/Try>`_.
+
+Try Task Config
+:::::::::::::::
+
+The second, more modern method specifies exactly the tasks to run. That list
+of tasks is usually generated locally with some :doc:`local tool </tools/try/selectors/fuzzy>`
+and attached to the commit pushed to the try repository. This gives
+finer control over exactly what runs and enables growth of an
+ecosystem of tooling appropriate to varied circumstances.
+
+Implementation
+,,,,,,,,,,,,,,
+
+This method uses a checked-in file called ``try_task_config.json`` which lives
+at the root of the source dir. The JSON object in this file contains a
+``tasks`` key giving the labels of the tasks to run. For example, the
+``try_task_config.json`` file might look like:
+
+.. parsed-literal::
+
+ {
+ "version": 1,
+ "tasks": [
+ "test-windows10-64/opt-web-platform-tests-12",
+ "test-windows7-32/opt-reftest-1",
+ "test-windows7-32/opt-reftest-2",
+ "test-windows7-32/opt-reftest-3",
+ "build-linux64/debug",
+ "source-test-mozlint-eslint"
+ ]
+ }
+
+Very simply, this will run any task label that gets passed in as well as their
+dependencies. While it is possible to manually commit this file and push to
+try, it is mainly meant to be a generation target for various :ref:`try server <Pushing to Try>`
+choosers. For example:
+
+.. parsed-literal::
+
+ $ ./mach try fuzzy
+
+A list of all possible task labels can be obtained by running:
+
+.. parsed-literal::
+
+ $ ./mach taskgraph tasks
+
+A list of task labels relevant to a tree (defaults to mozilla-central) can be
+obtained with:
+
+.. parsed-literal::
+
+ $ ./mach taskgraph target
+
+Modifying Tasks in a Try Push
+,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
+
+It's possible to alter the definition of a task by defining additional
+configuration in ``try_task_config.json``. For example, to set an environment
+variable in all tasks, you can add:
+
+.. parsed-literal::
+
+ {
+ "version": 1,
+ "tasks": [...],
+ "env": {
+ "FOO": "bar"
+ }
+ }
+
+The allowed configs are defined in :py:obj:`taskgraph.decision.try_task_config_schema`.
+The values will be available to all transforms, so how each config applies will
+vary wildly from one context to the next. Some (such as ``env``) will affect
+all tasks in the graph. Others might only affect certain kinds of task. The
+``use-artifact-builds`` config only applies to build tasks for instance.
+
+Empty Try
+:::::::::
+
+If there is no try syntax or ``try_task_config.json``, the ``try_mode``
+parameter is None and no tasks are selected to run. The resulting push will
+only have a decision task, but one with an "add jobs" action that can be used
+to add the desired jobs to the try push.
+
+
+Complex Configuration
+:::::::::::::::::::::
+
+If you need more control over the build configuration,
+(:doc:`staging releases </tools/try/selectors/release>`, for example),
+you can directly specify :doc:`parameters <parameters>`
+to override from the ``try_task_config.json`` like this:
+
+.. parsed-literal::
+
+ {
+ "version": 2,
+ "parameters": {
+ "optimize_target_tasks": true,
+ "release_type": "beta",
+ "target_tasks_method": "staging_release_builds"
+ }
+ }
+
+This format can express a superset of the version 1 format, as the
+version one configuration is equivalent to the following version 2
+config.
+
+.. parsed-literal::
+
+ {
+ "version": 2,
+ "parameters": {
+ "try_task_config": {...},
+ "try_mode": "try_task_config",
+ }
+ }
+
+.. _SCM Level: https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/