Closed Bug 1381622 Opened 2 years ago Closed 2 years ago

Update actions.json docs

Categories

(Taskcluster :: Services, enhancement)

enhancement
Not set

Tracking

(Not tracked)

RESOLVED FIXED
mozilla56

People

(Reporter: dustin, Assigned: dustin)

Details

Attachments

(5 files)

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.
----
Attachment #8887217 - Flags: feedback?(bstack)
Assignee: nobody → dustin
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
Attachment #8887214 - Flags: review?(jopsen) → review+
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.
Attachment #8887215 - Flags: review?(jopsen) → review+
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/
Attachment #8887216 - Flags: review?(jopsen) → review+
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?
Attachment #8887217 - Flags: review?(jopsen) → review-
Comment on attachment 8887548 [details]
Bug 1381622: add a 'name' property to actions;

https://reviewboard.mozilla.org/r/158416/#review163738
Attachment #8887548 - Flags: review?(jopsen) → review+
Comment on attachment 8887217 [details]
Bug 1381622: add UI considerations for actions;

https://reviewboard.mozilla.org/r/158004/#review163744
Attachment #8887217 - Flags: review?(jopsen) → review+
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
Component: Documentation → Services
You need to log in before you can comment on or make changes to this bug.