Bug 1473636: clarify arguments to action callbacks; r=tomprince

MozReview-Commit-ID: j3OiNkjngD

--HG--
extra : rebase_source : c1c169f5c1295628fe3ea5608407bd85cec34a00

taskcluster/docs/actions.rst

@@ -58,11 +58,22 @@ To create a new callback action you must create a file
       order=10000,  # Order in which it should appear relative to other actions
   )
   def hello_world_action(parameters, graph_config, input, task_group_id, task_id, task):
-      # parameters is an instance of taskgraph.parameters.Parameters
-      # it carries decision task parameters from the original decision task.
-      # input, task_id, and task should all be None
       print "Hello was triggered from taskGroupId: " + taskGroupId
 
+The arguments are:
+``parameters``
+  an instance of ``taskgraph.parameters.Parameters``, carrying decision task parameters from the original decision task.
+``graph_config``
+  an instance of ``taskgraph.config.GraphConfig``, carrying configuration for this tree
+``input``
+  the input from the user triggering the action (if any)
+``task_group_id``
+  the target task group on which this action should operate
+``task_id``
+  the target task on which this action should operate (or None if it is operating on the whole group)
+``task``
+  the definition of the target task (or None, as for ``task_id``)
+
 Callback actions are configured in-tree to generate 3 artifacts when they run.
 These artifacts are similar to the artifacts generated by decision tasks since
 callback actions are basically mini decision tasks. The artifacts are:

taskcluster/mach_commands.py

@@ -233,8 +233,10 @@ class MachCommands(MachCommandBase):
         try:
             self.setup_logging()
 
-            task_group_id = os.environ.get('ACTION_TASK_GROUP_ID', None)
+            # the target task for this action (or null if it's a group action)
             task_id = json.loads(os.environ.get('ACTION_TASK_ID', 'null'))
+            # the target task group for this action
+            task_group_id = os.environ.get('ACTION_TASK_GROUP_ID', None)
             input = json.loads(os.environ.get('ACTION_INPUT', 'null'))
             callback = os.environ.get('ACTION_CALLBACK', None)
             parameters = json.loads(os.environ.get('ACTION_PARAMETERS', '{}'))

taskcluster/taskgraph/actions/registry.py

@@ -166,6 +166,7 @@ def register_callback_action(name, title, symbol, description, order=10000,
                 'name': name,
                 'title': title,
                 'description': description,
+                # target taskGroupId (the task group this decision task is creating)
                 'taskGroupId': task_group_id,
                 'cb_name': cb.__name__,
                 'symbol': symbol,
@@ -241,8 +242,8 @@ def register_callback_action(name, title, symbol, description, order=10000,
                         # and pass everything else through from our own context
                         "user": {
                             'input': {'$eval': 'input'},
-                            'taskId': {'$eval': 'taskId'},
-                            'taskGroupId': {'$eval': 'taskGroupId'},
+                            'taskId': {'$eval': 'taskId'},  # target taskId (or null)
+                            'taskGroupId': {'$eval': 'taskGroupId'},  # target task group
                         }
                     },
                 })
@@ -303,7 +304,7 @@ def trigger_action_callback(task_group_id, task_id, input, callback, parameters,
         create.testing = True
         taskcluster.testing = True
 
-    # fetch the task, if taskId was given
+    # fetch the target task, if taskId was given
     # FIXME: many actions don't need this, so move this fetch into the callbacks
     # that do need it
     if task_id: