Sylvestre Ledru
b59392716e
Convert taskcluster/docs/*.rst (including transforms, kinds, optimization, howto subdirectories) and gecko_taskgraph test docs to MyST-flavored Markdown. Refresh allowed-warnings glob for release-promotion-action from .rst to .md. Differential Revision: https://phabricator.services.mozilla.com/D304225
143 lines
4.1 KiB
Markdown
143 lines
4.1 KiB
Markdown
# 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 two methods for scheduling a task on try: try task config, and an empty 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:
|
|
|
|
```{eval-rst}
|
|
.. 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:
|
|
|
|
```{eval-rst}
|
|
.. parsed-literal::
|
|
|
|
$ ./mach try fuzzy
|
|
```
|
|
|
|
A list of all possible task labels can be obtained by running:
|
|
|
|
```{eval-rst}
|
|
.. parsed-literal::
|
|
|
|
$ ./mach taskgraph tasks
|
|
```
|
|
|
|
A list of task labels relevant to a tree (defaults to mozilla-central) can be
|
|
obtained with:
|
|
|
|
```{eval-rst}
|
|
.. 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:
|
|
|
|
```{eval-rst}
|
|
.. 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:
|
|
|
|
```{eval-rst}
|
|
.. 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.
|
|
|
|
```{eval-rst}
|
|
.. 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/
|