balena-io
Migrate tabular commands to new output framework
This PR updates all the commands that output tabular data to use the new output framework (behind v14 flag). The output framework has been updated to include extra features that we needed in the commands. You can test v14 using the global --v-next flag.
A few other things:
balena release has highlighted an output artifact that we probably should discuss how to solve (regarding formatting of multi-line values) - see comments.
balena key output has been modified a bit - it's now IMO a bit cleaner
balena os versions is not included, since it requires some discussion.
We still have the issue with oclif's buggy json output. I've been looking into it, and it might be difficult to solve without more extensive changes to the oclif code (though I haven't reached a conclusion yet). If it turns out to be especially problematic, one options is to add our own json output implementation to the output framework (which will probably mean temporarily excluding other output flags when using the json flag). This only affects multi-record output. All output changes are behind the v14 flag though, so it's safe to merge this in the mean time.
There's currently an unresolved issue with the hideNullOrUndefinedValues option, due to the way oclif structures it's output. (see skipped tests).
Your landr site preview has been successfully deployed to https://landr-balena-io-repo-balena-cli-preview-2438.netlify.app
Deployed with Landr 9.4.12
Why is this change hidden behind an
is v14check?
@LucianBuzzo it's a breaking change that will require a new major version, and this is how we have handled major versions to date.
@srlowe Right, so do you consider any change in visual output a breaking change?
Right, so do you consider any change in visual output a breaking change?
@LucianBuzzo Paulo has quite strong views on not breaking things for people who may be scripting against the CLI, so we've agreed a joint approach that significant output changes would only happen during major releases. (And smaller changes on a case by case basis).
@srlowe @pdcastro Have you discussed supporting a --json flag for commands to support users who may script against the CLI, allowing more freedom in the visual presentation? Right now it's analogous to not changing a website in case people are scraping it.
@LucianBuzzo Right, one of the things this PR adds is a standard --json flag across all commands that output structured data. So this should make scripting much easier and frees us from worrying about changes to the presentation so much.
Right now it's analogous to not changing a website in case people are scraping it.
I don't think this is a fair analogy, especially in relation to the --json option and other data output formatting options. Web dashboards are not generally considered scripting tools and scraping them is very much "at your own risk", but command line interfaces are often used to automate tasks, piping stdin / stderr / stdout in shell scripts.
I think it is reasonable to use major version releases for "breaking changes" to data output format, but this should not prevent improvements from being made. Feature switches like isV14() are a way of grouping breaking changes to be released together. We could/should also release major versions more often than we have historically done. I would not have any problems with a new major version every month, and this could even avoid the need of feature switches in some cases, like I suppose this PR. (Cameron used to object to frequent major version releases, but he's not around anymore.) :-)
We have a GDoc where we keep track of a "wish list" of changes that we would like to group together for the next major. Perhaps we could move that GDoc to a public wiki page in this repo.
Paulo has quite strong views on not breaking things for people who may be scripting against the CLI,
It is true :-) and it only comes up here because I was asked to wear the loosely defined hat of "balena CLI maintainer" -- alongside Scott -- which makes me feel responsible for what is done to the balena CLI. Take that hat away from me, make the balena CLI "someone else's problem", and my views will not be nearly as strong. :-)
Thanks for the response @pdcastro . If every command supported --json and we made guarantees about the exit codes do you think that would be enough to support users scripting against the CLI, whilst decoupling data from aesthetics?
If every command supported
--jsonand we made guarantees about the exit codes do you think that would be enough to support users scripting against the CLI, whilst decoupling data from aesthetics?
That would go a long way, and I think this PR delivers some of it. Other considerations regarding scripting are mentioned in #1089 - e.g. when in "non-interactive mode", avoid colours and unicorns that make it harder for a script to determine whether an operation was successful, fail with an exit code instead of interactively asking for missing or ambiguous input* (which either makes scripting significantly more complex, or causes script to hang while CLI waits on stdin), better separation of stdout and stderr as per traditional CLI conventions/guidelines, avoiding debugging messages when --json is used (#2447).
Most of the above is the opposite of what would be considered user friendly if a person was interactively running CLI commands, which I think makes it necessary for the balena CLI to have two modes of operation: interactive mode and non-interactive (or scripting) mode. Both modes "reduce user friction", just in different use case scenarios.
