Bug 1296842: better parameter documentation to help readers; r?jmaher
MozReview-Commit-ID: N9EHe2s6PS
--- a/taskcluster/docs/parameters.rst
+++ b/taskcluster/docs/parameters.rst
@@ -6,16 +6,21 @@ Task-graph generation takes a collection
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 rougly by
topic.
Push Information
----------------
``base_repository``
The repository from which to do an initial clone, utilizing any available
@@ -61,19 +66,20 @@ 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.
+ The `SCM level
+ <https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/>`_
+ associated with this tree. This dictates the names of resources used in the
+ generated tasks, and those tasks will fail if it is incorrect.
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