I kept confusing myself looking at these docs, so I edited them up a bit: * refer to JSON-e * re-ordered to put the spec before the implementation * split out the UI considerations

Comment on attachment 8887217 [details] Bug 1381622: add UI considerations for actions; This last bit is a little tongue-in-cheek: ---- 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. The user interface should find the appropriate action by deep-comparing schemas, just like for specialized input. If no matching action is found, an error message should be presented to the user. Tasks without schemas cannot be triggered by custom UI elements. ---- I'd like to propose adding a "name" field that is not displayed to the user, but that can be used to find actions. Then: ---- The user interface should find the appropriate action by looking for an available action with a well-defined name. If there are several matching actions, select the first match. Once the action is found, the UI can generate suitable input and verify it against the schema. The UI may *optionally* use the deep comparison technique described above and show a fallback UI for unfamiliar schemas. Alternately, it may generate the action input unconditionally and only present an error to the user if the validation fails. The latter solution permits backward-compatible changes to action schemas. ----

I support the change you suggest in comment 5. Other than that, everything looks great.

OK, updated to add the security-related bits we talked about. I need to spend a little more time adding the "name" field, but otherwise this will be largely as described in comment 5.

Comment on attachment 8887214 [details] Bug 1381622: refer to JSON-e for template language; https://reviewboard.mozilla.org/r/157998/#review163200

Comment on attachment 8887215 [details] Bug 1381622: order the actions docs more naturally; https://reviewboard.mozilla.org/r/158000/#review163204 ::: taskcluster/docs/actions.rst:13 (Diff revision 1) > > * The decision task produces an artifact indicating what actions are > available. > > - * The user interface consults that artifact and presents appropriate choices > - to the user, possibly involving gathering additional data from the user, > + * A user interface (for example, Treeherder or the Taskcluster tools) consults > + that artifact and presents appropriate choices to the user, if necessary "that artifact" is a little unspecific... I know what you mean, but reader might not.

Comment on attachment 8887216 [details] Bug 1381622: re-order action spec sections and include more examples; https://reviewboard.mozilla.org/r/158002/#review163206 ::: taskcluster/docs/action-spec.rst:31 (Diff revision 1) > > +Actions > +------- > > -Specification of Actions > ------------------------- > +The content of ``actions.json`` is a list of actions (and variables, to be > +described later). Each action hsa a ``kind`` describing how a user interface s/hsa/has/

Comment on attachment 8887217 [details] Bug 1381622: add UI considerations for actions; https://reviewboard.mozilla.org/r/158004/#review163208 ::: taskcluster/docs/action-uis.rst:26 (Diff revision 2) > + > + * 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. Add the security consideration here... that same roles as was awarded the decision tasks should be used in `authorizedScopes` (this doesn't have to be the only place we mention it) ::: taskcluster/docs/action-uis.rst:27 (Diff revision 2) > + * 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. > + nit trailing space... ::: taskcluster/docs/action-uis.rst:71 (Diff revision 2) > +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. > + > +The user interface should find the appropriate action by deep-comparing > +schemas, just like for specialized input. If no matching action is found, an So you want to use `action.name` here, but leave deep comparison for the "specialized input" section, right?

Comment on attachment 8887548 [details] Bug 1381622: add a 'name' property to actions; https://reviewboard.mozilla.org/r/158416/#review163738

Comment on attachment 8887217 [details] Bug 1381622: add UI considerations for actions; https://reviewboard.mozilla.org/r/158004/#review163744

Pushed by dmitchell@mozilla.com: https://hg.mozilla.org/integration/autoland/rev/050b7291d367 refer to JSON-e for template language; r=jonasfj https://hg.mozilla.org/integration/autoland/rev/ce23a45500a5 order the actions docs more naturally; r=jonasfj https://hg.mozilla.org/integration/autoland/rev/f639c0a09d0f re-order action spec sections and include more examples; r=jonasfj https://hg.mozilla.org/integration/autoland/rev/40f39b9c423a add a 'name' property to actions; r=jonasfj https://hg.mozilla.org/integration/autoland/rev/e25a40d8d796 add UI considerations for actions; r=jonasfj

https://hg.mozilla.org/mozilla-central/rev/050b7291d367 https://hg.mozilla.org/mozilla-central/rev/ce23a45500a5 https://hg.mozilla.org/mozilla-central/rev/f639c0a09d0f https://hg.mozilla.org/mozilla-central/rev/40f39b9c423a https://hg.mozilla.org/mozilla-central/rev/e25a40d8d796