1381622 - Update actions.json docs

Status: RESOLVED FIXED

(Taskcluster :: Services, enhancement)

Description

[Dustin J. Mitchell [:dustin] (he/him)]

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 1

[Dustin J. Mitchell [:dustin] (he/him)]

Attachment: Bug 1381622: refer to JSON-e for template language;

Review commit: https://reviewboard.mozilla.org/r/157998/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/157998/

Comment 2

[Dustin J. Mitchell [:dustin] (he/him)]

Attachment: Bug 1381622: order the actions docs more naturally;

Review commit: https://reviewboard.mozilla.org/r/158000/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/158000/

Comment 3

[Dustin J. Mitchell [:dustin] (he/him)]

Attachment: Bug 1381622: re-order action spec sections and include more examples;

Review commit: https://reviewboard.mozilla.org/r/158002/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/158002/

Comment 4

[Dustin J. Mitchell [:dustin] (he/him)]

Attachment: Bug 1381622: add UI considerations for actions;

Review commit: https://reviewboard.mozilla.org/r/158004/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/158004/

Comment 5

[Dustin J. Mitchell [:dustin] (he/him)]

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.
----

Comment 6

[Brian Stack [:bstack]]

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

Comment 7

[Dustin J. Mitchell [:dustin] (he/him)]

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 8

[Dustin J. Mitchell [:dustin] (he/him)]

Comment on attachment 8887217 [details]
Bug 1381622: add UI considerations for actions;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/158004/diff/1-2/

Comment 9

[Jonas Finnemann Jensen (:jonasfj)]

Comment on attachment 8887214 [details]
Bug 1381622: refer to JSON-e for template language;

https://reviewboard.mozilla.org/r/157998/#review163200

Comment 10

[Jonas Finnemann Jensen (:jonasfj)]

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 11

[Jonas Finnemann Jensen (:jonasfj)]

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 12

[Jonas Finnemann Jensen (:jonasfj)]

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 13

[Dustin J. Mitchell [:dustin] (he/him)]

Attachment: Bug 1381622: add a 'name' property to actions;

This name can be used by user interfaces to find the action corresponding to a
dedicaetd UI element.

Review commit: https://reviewboard.mozilla.org/r/158416/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/158416/

Comment 14

[Dustin J. Mitchell [:dustin] (he/him)]

Comment on attachment 8887215 [details]
Bug 1381622: order the actions docs more naturally;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/158000/diff/1-2/

Comment 15

[Dustin J. Mitchell [:dustin] (he/him)]

Comment on attachment 8887216 [details]
Bug 1381622: re-order action spec sections and include more examples;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/158002/diff/1-2/

Comment 16

[Dustin J. Mitchell [:dustin] (he/him)]

Comment on attachment 8887217 [details]
Bug 1381622: add UI considerations for actions;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/158004/diff/2-3/

Comment 17

[Jonas Finnemann Jensen (:jonasfj)]

Comment on attachment 8887548 [details]
Bug 1381622: add a 'name' property to actions;

https://reviewboard.mozilla.org/r/158416/#review163738

Comment 18

[Jonas Finnemann Jensen (:jonasfj)]

Comment on attachment 8887217 [details]
Bug 1381622: add UI considerations for actions;

https://reviewboard.mozilla.org/r/158004/#review163744

Comment 19

[Pulsebot]

Pushed by [e-mail]:
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

Comment 20

[Ryan VanderMeulen [:RyanVM]]

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