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

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

Hi,

And one more toplevel reply, there is something I think was overlooked
that is relevant to this proposal.

On Fri, 2018-08-24 at 13:06 +0100, William Salmon via BuildStream-list wrote:
> Hi all,
>
> As recently raised by Tristan [1], there are numerous related issues & hanging 
> merge requests revolving around improvements & new functionality for BuildStream 
> workspaces. As such it make sense to address them in a common proposal which 
> hopefully addresses & highlights any overlapping or common changes needed to 
> meet the respective goals. Tackling & grouping related requests together also 
> means that if we have to conclude that a CLI change is needed [2], then it can 
> be done once to minimise & hopefully mitigate further changes. It's also 
> important to understand how any changes to the CLI could be consumed, in the 
> sense of a user (porcelain) or in automation (machine readable) so any feedback 
> from those perspectives is welcome.

There has been talk of this "porcelain" vs "machine readable", and
while there are some caveats to the current approach, I still like the
current approach, I don't believe was really discussed in this thread
(maybe I missed something ?).

To give a basic outline of the current approach:

  * All output that is considered only UI, is always sent to stderr

  * All output that is considered plausibly scriptable, is considered
    API stable, and sent to stdout

The main caveat which was raised with this, is the current behavior of
`bst workspace list`.

It outputs YAML to stdout, with the consideration that YAML is mostly
human readable and it is important for IDEs to be able to parse;
however it was raised that especially the output when no workspaces are
open only makes sense to machines but not humans, i.e. the empty list
`[]` which is sent to stdout.

Changing this is also an API break and I feel should be lumped into the
same discussion.

Note that further than this, there is the `bst artifact` subgroup
command which will be listing a bunch of new things which are
interesting for scriptability - I think that for most of that stuff we
should follow a similar paradigm that we do for `bst show`, which is:

  * Have a default formatting of what we want to display about an
    artifact, which is targetted at users; this still goes to stdout.

    Let's consider the default of this API unstable

  * Allow the `--format "%{foo} %{bar}"` option to dictate more
    precisely exactly what we want to output, including any separators
    a script might place there to allow for easy parsing of the output.

To handle the unfortunate case of `bst workspace list`, I feel that
just printing an additional UI message to stderr such as:

  "No workspaces found, printing an empty list"

Would be less than perfect but good enough for the sake of the YAML
formatted workspace list going to stdout.

Alternatives to this seem to revolve around adding a whole new option
to disambiguate machine readable output from user targetted UI - I
rather dislike this if it's really mostly going to be for this
workspace list issue.

Thoughts ?

Cheers,
    -Tristan