Bug 1381622: add UI considerations for actions; r=jonasfj
authorDustin J. Mitchell <dustin@mozilla.com>
Mon, 17 Jul 2017 20:39:08 +0000
changeset 418200 e25a40d8d796db2f2c5c13e4089a2b03e7ef63f5
parent 418199 40f39b9c423a94560e002276f40f1ee974ec0960
child 418201 1ba8ed71c08471ed9cf54f167a234eb6e285be54
push id7566
push usermtabara@mozilla.com
push dateWed, 02 Aug 2017 08:25:16 +0000
treeherdermozilla-beta@86913f512c3c [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjonasfj
bugs1381622
milestone56.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1381622: add UI considerations for actions; r=jonasfj MozReview-Commit-ID: CuhPkD3Xbic
taskcluster/docs/action-spec.rst
taskcluster/docs/action-uis.rst
taskcluster/docs/actions.rst
--- a/taskcluster/docs/action-spec.rst
+++ b/taskcluster/docs/action-spec.rst
@@ -208,33 +208,21 @@ specified with by the action's ``schema`
     ],
     "variables: {},
   }
 
 User interfaces for triggering actions, like Treeherder, are expected to provide
 JSON input that satisfies this schema. These interfaces are also expected to
 validate the input against the schema before attempting to trigger the action.
 
-It is expected that such user interfaces will attempt to auto-generate HTML
-forms from JSON schema specified. However, a user-interface implementor may also
-decide to hand write an HTML form for a particularly common or complex JSON
-schema. As long as the input generated from the form conforms to the schema
-specified for the given action. To ensure that, implementers should do a deep
-comparison between a schema for which a hand-written HTML form exists, and the
-schema required by the action.
-
 It is perfectly legal to reference external schemas using
 constructs like ``{"$ref": "https://example.com/my-schema.json"}``, in this case
 it however strongly recommended that the external resource is available over
 HTTPS and allows CORS requests from any source.
 
-In fact, user interface implementors should feel encouraged to publish schemas
-for which they have hand written input forms, so that action developers can
-use these when applicable.
-
 When writing schemas it is strongly encouraged that the JSON schema
 ``description`` properties are used to provide detailed descriptions. It is
 assumed that consumers will render these ``description`` properties as markdown.
 
 
 Variables
 ---------
 
new file mode 100644
--- /dev/null
+++ b/taskcluster/docs/action-uis.rst
@@ -0,0 +1,87 @@
+User Interface Considerations
+=============================
+
+The actions system decouples in-tree changes from user interface changes by
+taking advantage of graceful degradation. User interfaces, when presented with
+an unfamiliar action, fall back to a usable default behavior, and can later be
+upgraded to handle that action with a more refined approach.
+
+Default Behavior
+----------------
+
+Every user interface should support the following:
+
+ * Displaying a list of actions relevant to each task, and displaying
+   task-group tasks for the associated task-group.
+
+ * Providing an opportuntity for the user to enter input for an action.  This
+   might be in JSON or YAML, or using a form auto-generated from the action's
+   JSON-schema.  If the action has no schema, this step should be skipped.
+   The user's input should be validated against the schema.
+
+ * For ``action.kind = 'task'``, rendering the template using the JSON-e
+   library, using the variables described in :doc:`action-spec`.
+
+ * Calling ``Queue.createTask`` with the resulting task, using the user's
+   Taskcluster credentials.  See the next section for some important
+   security-related concerns.
+
+Creating Tasks
+--------------
+
+When executing an action, a UI must ensure that the user is authorized to
+perform the action, and that the user is not being "tricked" into executing
+an unexpected action.
+
+To accomplish the first, the UI should create tasks with the user's Taskcluster
+credentials. Do not use credentials configured as part of the service itself!
+
+To accomplish the second, use the decision tasks's ``scopes`` property as the
+`authorizedScopes
+<https://docs.taskcluster.net/manual/design/apis/hawk/authorized-scopes>`_ for
+the ``Queue.createTask`` call.  This prevents action tasks from doing anything
+the original decision task couldn't do.
+
+Specialized Behavior
+--------------------
+
+The default behavior is too clumsy for day-to-day use for common actions.  User
+interfaces may want to provide a more natural interface that still takes advantage
+of the actions system.
+
+Specialized Input
+.................
+
+A user interface may provide specialized input forms for specific schemas.  The
+input generated from the form must conform to the schema.
+
+To ensure that the schema has not changed, implementers should do a deep
+comparison between a schema for which a hand-written form exists, and the
+schema required by the action. If the two differ, the default behavior should
+be used instead.
+
+Specialized Triggering
+......................
+
+A user interface may want to trigger a specific action using a dedicated UI
+element.  For example, an "start interactive session" button might be placed
+next to each failing test in a list of tests.
+
+User interfaces should look for the desired action by name. The UI should check
+that there is exactly one matching action available for the given task or
+task-graph. If multiple actions match, the UI should treat that as an error
+(helping to avoid actions being surreptitiously replaced by similarly-named,
+malicious actions).
+
+Having discovered the task, the user interface has a choice in how to provide
+its input. It can use the "specialized input" approach outlined above, providing
+a customized form if the action's schema is recognized and gracefully degrading
+if not.
+
+But if the user interface is generating the input internally, it may instead
+validate that generated input against the action's schema as given, proceeding
+if validation succeeds.  In this alternative, there is no need to do a deep
+comparison of the schema.  This approach allows in-tree changes that introduce
+backward-compatible changes to the schema, without breaking support in user
+interfaces.  Of course, if the changes are not backward-compatibile, breakage
+will ensue.
--- a/taskcluster/docs/actions.rst
+++ b/taskcluster/docs/actions.rst
@@ -19,9 +19,10 @@ At a very high level, the process looks 
    task", including the provided information. That action task is responsible
    for carrying out the named action, and may create new sub-tasks if necessary
    (for example, to re-trigger a task).
 
 
 .. toctree::
 
     action-spec
+    action-uis
     action-implementation