Bug 1296842: better parameter documentation to help readers; r=jmaher
authorDustin J. Mitchell <dustin@mozilla.com>
Mon, 07 Nov 2016 15:02:13 +0000
changeset 348164 4a1847c6164f36f770d18adae40b6f582030c2a6
parent 348163 c7a47678290a380324b9bc9704b21c9f3c116af3
child 348165 8d60c718ff153d8982141e93414e1a412996291a
push id10298
push userraliiev@mozilla.com
push dateMon, 14 Nov 2016 12:33:03 +0000
treeherdermozilla-aurora@7e29173b1641 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
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