Re: [BuildStream] Proposal: Workspace related DX features & design

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

Hi Sander,

Sorry for the delayed response...

On Tue, 2018-09-04 at 10:16 -0400, Sander Striker wrote:
> Hi Tristan,
>
> On Tue, Sep 4, 2018 at 3:03 PM Tristan Van Berkom <tristan vanberkom codethink co uk> wrote:
> > Hi Chandan,
> >
> > On Tue, 2018-09-04 at 12:55 +0100, Chandan Singh wrote:
> > > Hi all,
> > >  
> > > I like Tristan's idea of --open better than --multi but I don't think
> > > it is very intuitive from users' point of view. It definitely allows
> > > us to provide a very feature-rich CLI but that might come at the cost
> > > of user experience.
> > >  
> > > As a user, I would probably expect to run `bst workspace open foo.bst
> > > bar.bst` and not end up with a workspace for foo.bst in a directory
> > > called bar.bst. In my opinion, it is intuitive for this command to
> > > open workspaces for both elements since that is exactly how the other
> > > two workspace commands (close and reset) work, i.e. by accepting a
> > > list of elements as arguments. --open would introduce a weird
> > > asymmetry between `open` and other workspace commands. (open is
> > > already different from the other two commands, but I think we should
> > > try to close the gap instead.)
> > >  
> > > If we are allowed to break API once, I would like to propose the
> > > following syntax:
> > >  
> > >     bst workspace open ELEMENT [ELEMENT ...] [--directory DIR]
> > >  
> > > This approach has a downside that users will not be able to specify
> > > different locations for different elements in the same bst invocation.
> > > But I don't think that that is a very common use-case and that the
> > > directory argument, in general, might see less use once we allow
> > > configuring default locations for workspaces. Even though it will be a
> > > bit restrictive, I think it will still do what it says on the tin,
> > > i.e. open workspaces for all elements in the directory specified by
> > > --directory option, which can default to '.' ($CWD).
> > >  
> > > Just my 2 cents. Thoughts?
> >
> > I do take your point, however; did you take into consideration that
> > with my counter proposal, we get to completely do away with this pesky
> > `--directory` argument altogether ?
> >
> > I find this `--directory` thing quite obnoxious, especially as it is
> > intended to not be used after the user configures a directory, but is
> > somehow *required* if you want to place your workspace in a custom
> > location.
>
> Is there a better name for it than '--directory' that makes the
> behavior more obvious?
>
> FWIW I take your point, I'm not sold on --directory either.  Mostly
> because of the counterintuitive behavior when using it in the context
> of opening a single element.  I don't believe there is a way to point
> to a custom path to a workspace that isn't derived from element name
> in the current proposal.
> Now, I personally think that discouraging use of custom paths for
> workspaces is generally a good thing.  However, we shouldn't make it
> impossible. 

I rather also don't like that:

  * If you specify --directory, you have to *also* specify the
    workspacename, which is part of the path; this is redundant

  * You MUST specify --directory until you have tediously selected
    a default location

> > We have a much more intuitive experience when the optional directory
> > argument is a path and not a "workspacename", which can be absolute or
> > relative, and when relative is appended to the default location.
>
> Being pedantic, where relative is appended to the default location if
> it doesn't start with ./ or ../.

I like this yes, might still be relevant with your `--path` proposal ?

> > On the other hand, I don't really expect humans to be opening multiple
> > workspaces at once; and would be happy to drop the feature entirely if
> > there wasn't significant push to make it possible to open multiple
> > workspaces at once.
>
> Ah.  Let's explore that further.
>  
> > Do we want to miss out on the opportunity to drop the `--directory`
> > argument, for the sake of a feature that I suspect almost nobody will
> > ever use, to be more intuitive ?
> >
> > I expect that the push for supporting opening multiple workspaces in a
> > single command is driven more by an expectation that it will be useful
> > in automated scripts and in IDEs (and will be a time saver to do it in
> > a single command in those contexts), rather than an expectation that
> > humans will be using this multi open command, am I wrong ?
>
> I think it depends on the way that people work.  A pattern I could
> see, is a user knowing he needs to make changes to app.bst, libA.bst
> and libB.bst.  And then opening workspaces for all of them in one go.
>
> I would argue that the context of IDEs you brought up is also human
> driven, and then the time saver is relevant in terms of user
> experience.
>
> I think we only have this one time where we can decide to support
> opening multiple workspaces.  If we don't do it now, I see the same
> CLI API breakage required in the future to be prohibitive.  As such I
> do think we need to a conscious decision here.
>
> We essentially now have what boils down to the following:
>
> A.  Support for custom workspace paths. No support for opening
> multiple workspaces.
> $ bst workspace open ELEMENT [PATH]
>
> B. No support for custom workspace paths. Support opening multiple
> workspaces.
> $ bst workspace open ELEMENT [ELEMENT ...]
>
> That isn't much of a choice, as not supporting custom workspace paths
> is not an option.  I can only think of one more option:
>
> C. Support for custom workspace paths.  Support opening multiple
> workspaces.
> $ bst workspace open --path PATH ELEMENT
> $ bst workspace open ELEMENT [ELEMENT ...]
>
> That is, when the --path option (or whatever name we choose), is
> specified you can only open a single workspace.  And when multiple
> workspaces are specified, you cannot use the --path option.  Where
> PATH is either an absolute directory (starts with /), a directory
> relative to the current directory (starts with ./), or a directory
> relative to the configured workspace directory.

I like this approach too !

So IIUC, essentially this means that:

  * There is no default location configured

  * I have to use `--path` when opening a workspace without any
    location specified in my buildstream.conf

  * When specifying `--path`, it will not append any automatically
    generated workspacename to my path, it will just use the path
    I specified as the workspace directory to open

Let's make sure to expand environment variables and `~/` in the
configuration of the default workspace location.

This also sounds much better to me than the original proposal, and
given that I still don't think opening of multiple workspaces is
something users will frequently do in a single command; I would rather
not be adamant about being able to specify every detail of every
workspace separately in a single command (which my proposal allowed,
but as some additional expense).

If people want different options for the multiple workspaces they want
to open, then can call `bst workspace open` multiple times.

Cheers,
    -Tristan