GNOME.org
 

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

On Thu, 2018-09-06 at 11:42 +0200, Sander Striker wrote:

Hi,


On Thu, Sep 6, 2018 at 10:24 AM Tristan Van Berkom via BuildStream-list <buildstream-list gnome org> 
wrote:
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 ?).


I don't think you missed the discussion.  I missed the mention of it
in the paragraph above, or at least didn't consciously pick it up.  I
think the topic is much broader in scope than the workspace UI.


Agreed,

It only overlaps because of `bst workspace list`, and I would hope to
get all plausible API breaks out of the way for peace of mind if that
is alright :)


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.


I think introduction of a --non-interactive option is almost the
equivalent of requiring the specification of --format when the
default output is considered unstable.  The biggest difference is
that we now no longer have a common default for machine readable
output, so everyone writing a script needs to start with looking what
to put in the format string, rather than looking at a reasonable
default.


I have always viewed the `bst show` formatting option as mandatory
for scriptability, but this is admittedly an unspoken view.

Mostly I viewed it this way because parsing the default output is
impractical, as such we have changed the defaults here without much
consideration, this is my fault.



For a use case of post processing captured output, we then require
coordination on what format string to use.  I could see this in the
case of the bst artifact family, which you raise above, where it is
expected that scripts exist to provide additional data based on the
parsed output.  I don't necessarily think that we would need to rerun
the same bst command multiple times just for different format
strings, if there is no real need other than a baked in --format.


We should not have to re-run the same `bst` command multiple times, the
`--format` argument as implemented in `bst` show allows for digging out
everything possible for a given "record" (or "element" more
specifically, in the case of `bst show`).


The introduction of a --non-interactive flag allows for tweaks that
benefit humans, without having to worry about interfering with
machines.


Here things get a bit more interesting:

  * We already have the --interactive/--no-interactive switch

  * This switch is turned on automatically if connected to a tty,
    otherwise it is turned off.

  * Running a command like `bst show element.bst | cat`,
    or running the following in a script:

      element_data=$(bst show element.bst)

    Effectively disconnects `bst` from the tty, regardless of whether
    the command was actually launched by a user from a shell.

If we wanted to provide API stability for the default formatting of
commands like `bst show` or tentatively `bst artifact show`, while
retaining the liberty of changing the defaults for the sake of users
only (is this what you are getting at ?), then would could effectively
do this with the existing "interactive" switch; without even requiring
that scripts ever specify `--no-interactive` in their invocations.

But, considering that usually we would expect a script to `--format`
their invocations to "show" commands for their own convenience anyway
(even if only for the sake of separating outputs with a `::` separator
or suchlike), would it make sense to keep API stability for the default
outputs at all ?

I feel like if we mandate scripts to specify `--format` if they want
API stable results, it is just as onerous as requiring a different
flag, while they will probably want to specify `--format` anyway, so
maybe it's better to only advertise API stability for invocations which
specify `--format` ?

Cheers,
    -Tristan
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]