Bug 1296842: better parameter documentation to help readers; r?jmaher draft
authorDustin J. Mitchell <dustin@mozilla.com>
Mon, 07 Nov 2016 15:02:13 +0000
changeset 434942 ed8b637c62789b256636a21f16287c8b59910c52
parent 434900 bb5895ace33fc2bbd37a99b7e20f091e3fee18d4
child 434943 746c8b91b050b5ecfd57a13fd6d19df231e0b07c
push id34880
push userdmitchell@mozilla.com
push dateMon, 07 Nov 2016 19:15:08 +0000
reviewersjmaher
bugs1296842
milestone52.0a1
Bug 1296842: better parameter documentation to help readers; r?jmaher MozReview-Commit-ID: N9EHe2s6PS
taskcluster/docs/parameters.rst
--- 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