bug 1355482 - release promotion doc review followup. r=bhearsum
authorAki Sasaki <asasaki@mozilla.com>
Thu, 22 Mar 2018 12:00:22 -0700
changeset 818022 a24da6e2347bd4cb2f7869c7249dc71b1ec5b5c3
parent 818021 3953416efafe56231a9367a2e33b4d7adc054878
child 818023 5b055ea068753af259b6bd69c70b58ad72d9a06a
push id116246
push userbmo:tom@mozilla.com
push dateFri, 13 Jul 2018 20:48:08 +0000
reviewersbhearsum
bugs1355482
milestone60.1.1
bug 1355482 - release promotion doc review followup. r=bhearsum
taskcluster/docs/release-promotion-action.rst
--- a/taskcluster/docs/release-promotion-action.rst
+++ b/taskcluster/docs/release-promotion-action.rst
@@ -1,15 +1,17 @@
 Release Promotion Action
 ========================
 
 The `release promotion action`_ allows us to chain multiple task groups, or graphs, together.
 Essentially, we're using :ref:`optimization` logic to replace task labels in the
 current task group with task IDs from the previous task group(s).
 
+.. _snowman model:
+
 The snowman model
 -----------------
 
 We chain task groups, or graphs, together to allow us to trigger sets of tasks
 at separate cadences. This is the ``snowman`` model. If you request the body of
 the snowman and point at the base, we only create the middle section of the snowman.
 If you request the body of the snowman and don't point it at the base, we build the
 first base and body of the snowman from scratch.
@@ -39,52 +41,52 @@ Now let's specify task group ``G1`` and 
     |         |         |
     t1        t0        |
       \________________ |
                        \|
                         t2
 
 For a more real-world example::
 
-|         G
-|         |
-|       build
-|         |
-|      signing
-|         |
-|    l10n-repack
-|         |
-|    l10n-signing
+         G
+         |
+       build
+         |
+      signing
+         |
+    l10n-repack
+         |
+    l10n-signing
 
 If we point the ``promote`` task group G at the on-push build task group ``G1``, the l10n-repack job will depend on the previously finished build and build-signing tasks::
 
-|         G1            G
-|         |             |
-|       build           |
-|         |             |
-|      signing          |
-|             \_________|
-|                       |
-|                  l10n-repack
-|                       |
-|                  l10n-signing
+         G1            G
+         |             |
+       build           |
+         |             |
+      signing          |
+             \_________|
+                       |
+                  l10n-repack
+                       |
+                  l10n-signing
 
 We can also explicitly exclude certain tasks from being optimized out.
 We currently do this by specifying ``rebuild_kinds`` in the action; these
 are :ref:`kinds` that we want to explicitly rebuild in the current task group,
 even if they existed in previous task groups. We also allow for specifying a list of
 ``do_not_optimize`` labels, which would be more verbose and specific than
 specifying kinds to rebuild.
 
 Release promotion action mechanics
 ----------------------------------
 
-The action downloads the ``parameters.yml`` from the initial ``previous_graph_id``.
-This is most likely the decision task of the revision to promote, which is generally
-the same revision the release promotion action is run against.
+There are a number of inputs defined in the `release promotion action`_. Among these are the ``previous_graph_ids``, which is an ordered list of taskGroupIds of the task groups that we want to build our task group, off of. In the :ref:`snowman model`, these define the already-built portions of the snowman.
+
+The action downloads the ``parameters.yml`` from the initial ``previous_graph_id``, which matches the decision- or action- taskId. (See :ref:`taskid vs taskgroupid`.) This is most likely the decision task of the revision to promote, which is generally the same revision the release promotion action is run against.
 
 .. note:: If the parameters have been changed since the build happened, *and* we explicitly want the new parameters for the release promotion action task, the first ``previous_graph_id`` should be the new revision's decision task. Then the build and other previous action task group IDs can follow, so we're still replacing the task labels with the task IDs from the original revision.
 
 The action then downloads the various ``label-to-taskid.json`` artifacts from each previous task group, and builds an ``existing_tasks`` parameter of which labels to replace with which task IDs. Each successive update to this dictionary overwrites existing keys with new task IDs, so the rightmost task group with a given label takes precedence. Any labels that match the ``do_not_optimize`` list or that belong to tasks in the ``rebuild_kinds`` list are excluded from the ``existing_tasks`` parameter.
 
 Once all that happens, and we've gotten our configuration from the original parameters and our action config and inputs, we run the decision task function with our custom parameters. The :ref:`optimization` phase replaces any ``existing_tasks`` with the task IDs we've built from the previous task groups.
 
 Release Promotion Flavors
@@ -110,16 +112,18 @@ Triggering the release promotion action 
 ----------------------------------------------------------
 
 `Releaserunner3`_ is our current method of triggering the release promotion action from Ship It in production. Examples of how to run this are in the `releasewarrior docs`_.
 
 To deal with the above ``previous_graph_ids`` logic, we allow for a ``decision_task_id`` in `trigger_action.py`_. As of 2018-03-14, this script assumes we want to download ``parameters.yml`` from the same decision task that we get ``actions.json`` from. At some point, we'd like the `trigger_action.py`_ call to happen automatically once we push a button on Ship It.
 
 The action task that's generated from ``actions.json`` matches the `.taskcluster.yml`_ template. This is important; Chain of Trust (v2) requires that the task definition be reproducible from `.taskcluster.yml`_.
 
+.. _taskid vs taskgroupid:
+
 Release promotion action taskId and taskGroupId
 -----------------------------------------------
 
 The ``taskGroupId`` of a release promotion action task will be the same as the ``taskId`` of the decision task.
 
 The ``taskGroupId`` of a release promotion *task group* will be the same as the ``taskId`` of the release promotion action task.
 
 So: