==========
Parameters
==========
Task-graph generation takes a collection of parameters as input, in the form of
a JSON or YAML file.
During decision-task processing, some of these parameters are supplied on the
command line or by environment variables. The decision task helpfully produces
a full parameters file as one of its output artifacts. The other ``mach
taskgraph`` commands can take this file as input. This can be very helpful
when working on a change to the task graph.
When experimenting with local runs of the task-graph generation, it is always
best to find a recent decision task's ``parameters.yml`` file, and modify that
file if necessary, rather than starting from scratch. This ensures you have a
complete set of parameters.
The properties of the parameters object are described here, divided roughly by
topic.
Push Information
----------------
``backstop``
Whether or not this push is a "backstop" push. That is a push where all
builds and tests should run to ensure regressions aren't accidentally
missed.
``base_repository``
The repository from which to do an initial clone, utilizing any available
caching.
``head_repository``
The repository containing the changeset to be built. This may differ from
``base_repository`` in cases where ``base_repository`` is likely to be cached
and only a few additional commits are needed from ``head_repository``.
``base_rev``
The previous revision before ``head_rev`` got merged into. This can be a short revision string.
``head_rev``
The revision to check out; this can be a short revision string
``base_ref``
Reference where ``head_rev`` got merged into. It is usually a branch or a tag.
``head_ref``
For Mercurial repositories, this is the same as ``head_rev``. For
git repositories, which do not allow pulling explicit revisions, this gives
the symbolic ref containing ``head_rev`` that should be pulled from
``head_repository``.
``head_tag``
The tag attached to the revision, if any.
``files_changed``
The list of all files added or modified by the push.
``owner``
Email address indicating the person who made the push. Note that this
value may be forged and *must not* be relied on for authentication.
``message``
The try syntax in the commit message, if any.
``pushlog_id``
The ID from the ``hg.mozilla.org`` pushlog
``pushdate``
The timestamp of the push to the repository that triggered this decision
task. Expressed as an integer seconds since the UNIX epoch.
``hg_branch``
The mercurial branch where the revision lives in.
``build_date``
The timestamp of the build date. Defaults to ``pushdate`` and falls back to present time of
taskgraph invocation. Expressed as an integer seconds since the UNIX epoch.
``moz_build_date``
A formatted timestamp of ``build_date``. Expressed as a string with the following
format: %Y%m%d%H%M%S
``repository_type``
The type of repository, either ``hg`` or ``git``.
``tasks_for``
The ``tasks_for`` value used to generate the decision task.
Tree Information
----------------
``project``
Another name for what may otherwise be called tree or branch or
repository. This is the unqualified name, such as ``mozilla-central`` or
``cedar``.
``level``
The `SCM level
`_
associated with this tree. This dictates the names of resources used in the
generated tasks, and those tasks will fail if it is incorrect.
Try Configuration
-----------------
``try_mode``
The mode in which a try push is operating. This can be one of:
* ``"try_task_config"`` - Used to configure the taskgraph.
* ``"try_option_syntax"`` - Used when pushing to try with legacy try syntax.
* ``"try_auto"`` - Used to make try pushes behave more like a push on ``autoland``.
* ``"try_select"`` - Used by ``mach try`` to build a list of tasks locally.
* ``None`` - Not a try push or ``mach try release``.
``try_options``
The arguments given as try syntax (as a dictionary), or ``None`` if
``try_mode`` is not ``try_option_syntax``.
``try_task_config``
The contents of the ``try_task_config.json`` file, or ``{}`` if
``try_mode`` is not ``try_task_config``.
Test Configuration
------------------
``test_manifest_loader``
The test manifest loader to use as defined in ``taskgraph.util.chunking.manifest_loaders``.
Target Set
----------
The "target set" is the set of task labels which must be included in a task
graph. The task graph generation process will include any tasks required by
those in the target set, recursively. In a decision task, this set can be
specified programmatically using one of a variety of methods (e.g., parsing try
syntax or reading a project-specific configuration file).
``enable_always_target``
Can either be a boolean or a list of kinds.
When ``True``, any task with the ``always_target`` attribute will be included
in the ``target_task_graph`` regardless of whether they were filtered out by
the ``target_tasks_method`` or not. Because they are not part of the
``target_set``, they will still be eligible for optimization when the
``optimize_target_tasks`` parameter is ``False``.
When specified as a list of kinds, only tasks with a matching kind will be
eligible for addition to the graph.
``filters``
List of filter functions (from ``taskcluster/gecko_taskgraph/filter_tasks.py``) to
apply. This is usually defined internally, as filters are typically
global.
``target_tasks_method``
The method to use to determine the target task set. This is the suffix of
one of the functions in ``taskcluster/gecko_taskgraph/target_tasks.py``.
``release_history``
History of recent releases by platform and locale, used when generating
partial updates for nightly releases.
Suitable contents can be generated with ``mach release-history``,
which will print to the console by default.
Optimization
------------
``optimize_strategies``
A python path of the form ``: