Re: [BuildStream] Bst workspace - UX feedback and change suggestions

[Tristan Van Berkom <tristan vanberkom codethink co uk>]

On Mon, 2018-08-06 at 18:30 +0100, Phillip Smyth via BuildStream-list
wrote:
> Hi everyone,
>
> Today I did a UX test with one of our newer contributers to see how
> intuitive the bst workspace UI is, and got some points that I feel
> are worth raising.

Thanks for reporting these findings !

> I gave the engineer the following directions:
>
> """
> Please do not touch the `files` directory in the project dir.
> You may look inside the `files` directory, but you may not modify or
> execute anything in there.
>
> Use bst workspace to modify the existing project from printing "Hello
> World" to "Goodbye World"
> Execute the program to confirm this worked.
>
> Finally please remove the workspace and confirm the dirctory is gone
> and that there are no more active workspaces.
> """

This does not invalidate the valuable feedback you've provided, but I
should say that I do not like this example, I think it would be a good
idea to:

  o Host an example git repository in our gitlab group, this would
    basically just be another hello world example with some autotools
    build scripts.

  o We could change the autotools example to use this instead of
    downloading the third party git that we do

  o Change the recently added workspace user guide to use the git
    repo instead of using a `local` source.

The reason I say this is because a workspace does not seem to be useful
for a "local" source. When someone tries using a workspace following
our examples, the fact that it's a local source can probably cause a
lot of confusion to the user about what workspaces are for.


> This is a repo of the project i used:
> https://gitlab.com/knownexus/hello-project
>
> From this I got the following feedback and reactions:
>
> 1) `bst workspace open` was not clear that it would automatically
> create the named directory if it did not exist.
>     This resulted in making the process feel more clunky and is the
> opposite of `bst init` which does not create a named directory, which
> makes the UX inconsistent.

I don't think the answer here is to strive for symmetry with `bst init`
(although bst init most certainly creates the project directory, when
one is specified, like `bst -C <project_dir> init ...`), I think that
`bst init` is sufficiently special.

Rather, I would read more deeply into this and think that the directory
is not the problem, it's the checkout.

I.e., if we're going to populate the workspace directory with the
content of what would be staged for that element; I think it makes
sense to expect we will create the directory.

Maybe the user in question did not expect the checkout to happen
automatically (i.e. we have --no-checkout, while the user might have
expected that to be the default, and --checkout would have to be
provided to explicitly prepare the checkout).

It would however be unfortunate change the CLI behavior in this regard,
because this is not merely UX, workspaces are scriptable (I've heard it
used this way, not sure how much that it's used in an automated
context).


> 2)  The closing of a workspace was not intuitive.
>     The user expected the directory to be deleted when closing the
> workspace.
>     And for the keeping of the directory to be the flag, not deletion
> of it.
>
>     A potential fix to this could be:
>     Diff the closing workspace, with a temporary new workspace, to
> see if any changes were made.
>     If no changes were made, remove the directory.
>     If changes are detected, display a prompt asking if the user
> wishes to continue deleting all changes made, and to re-run the
> command using `--keep-dir` if they wished to keep the directory.

Sort of ditto to the above point, it would be unfortunate to break the
CLI at this point.

I would be more happy about changing these two default behaviors if:

  o Others ring in and strongly agree that these proposed defaults
    are better.

  o People who do use workspace features in an automated context, agree
    that adjusting their automation scripts to deal with a breaking
    change is not too disruptive to them.


> 3) `bst workspace list` displays `[]` when no workspaces are found,
> instead of showing a message like "No workspaces found".
>     This would be far clearer than simply printing an empty list.

We should definitely add a user facing message to the stderr for this
purpose, removing the `[]` which goes to stdout is not that easily
done.

The stdout of `bst workspace list`, being YAML, is fairly human
readable when workspaces do exist; but it is a stable API surface which
also targets an automation setting - scripts will be parsing the output
of `bst workspace list`, and I think an empty list is more friendly
than nothing at all.

Rather, if we are going to break anything here, again I'd like to hear
from anyone who is using the automation first; and if we do make a
change, I would propose that we expose an option that informs bst that
we are talking to a machine and not a human (in a similar way to how
git makes this distinction with "--porcelain").

> I believe there are more UX features that could be addressed beyond
> that of workspaces, and would encourage others to do a similar
> process with other new and existing features,
> as I feel it helped a lot to get a fresh perspective and remove my
> own bias as a factor.

Indeed, and thanks again for the report !

Cheers,
    -Tristan