Forthcoming mas output overhaul

[rgoldberg]

Output of brew config

n/a

Output of brew doctor

n/a

Description of issue

mas will likely overhaul its output sometime in the upcoming months. (apologies if the mas issue is terse; I am happy to provide more detail where requested)

The overhaul will probably modify the default tabular output. It might provide options for displaying additional/different data, ordering it, etc. in the tabular output.

It will also provide 2 optional JSON formats: raw (mainly for debugging) & standard (mainly for programmatic use).

You should probably use the standard JSON output for any parsing. I haven’t yet chosen the property keys for standard JSON. They’ll be included in the aforementioned mas issue once I start to work on them.

From what I know, brew bundle parses some mas output (I don’t know if any other parts of brew do).

I’m happy to coordinate the output overhaul with all interested parties.

Please let me know:

• if any other non-bundle parts of brew use mas
• when someone from a part of brew that uses mas has joined this discussion so I know that all relevant parts of brew know about this
• where this migration should be tracked for each relevant part of brew
• if you know of any other projects that might parse mas output
• if you have any questions, concerns, comments, etc. about this overhaul

Thanks.

[MikeMcQuaid]

mas will likely overhaul its output sometime in the upcoming months. (apologies if the mas issue is terse; I am happy to provide more detail where requested)

@rgoldberg Please don't change the output format in a non-major release. Given you know that you have tools already parsing the output as-is: it'd be ideal to do one or more of:

• keep the same output for now
• keep the same output for now unless the user has a TTY (i.e. it's not being read/piped)
• require JSON output flags to change output

It will also provide 2 optional JSON formats: raw (mainly for debugging) & standard (mainly for programmatic use).

I would recommend providing a single JSON format rather than two.

You should probably use the standard JSON output for any parsing.

Eventually, we will, yes. However, we need a way to easily detect the version of mas and whether it even supports JSON output. As above, I'd suggest that moving to this (or adjusting the standard format) be considered a major version breaking change.

From what I know, brew bundle parses some mas output (I don’t know if any other parts of brew do).

Only brew bundle uses it.

• where this migration should be tracked for each relevant part of brew

We can't really track or plan a migration yet because you've said you haven't decided on the output format or what the keys would be. I'd strongly recommend, as a migration path:

1. add one JSON output format and document it
2. announce this format as stable (when it is)
3. announce how and when you're going to change the non-JSON format(s), ideally also with (stderr!) warnings in the CLI when used the way you don't want
4. make a major release
5. change/remove any output formats you don't want and point people towards JSON instead

[rgoldberg]

@MikeMcQuaid Thanks for the speedy reply.

I brought this up despite neither having drafted the standard JSON format nor having an exact timeline for implementation because I wanted to give you as much of a heads up as possible.

Is it best for me to open a new discussion here once the standard JSON format has been drafted? Then another discussion here once it is available to be tested / used?

mas will include the JSON output option(s) (& possibly options to explicitly change the tabular output) in a minor release (presumably 1.9); changing the default tabular output will be left for a major release (presumably 2.0).

I would recommend providing a single JSON format rather than two.

The raw JSON won't be a maintained format by mas; it will just pass through Apple-sourced data as is.

mas will want to provide both JSON formats because the Apple-sourced data is either undocumented or very loosely documented. It can change at any moment, so it'll be useful to have a way to pass through the raw Apple data to investigate if source data changes have caused problems for mas tabular or standard JSON output. Or if users or mas devs want to compare mas output to output they have obtained from Apple.

announce how and when you're going to change the non-JSON format(s), ideally also with (stderr!) warnings in the CLI when used the way you don't want

Do you mean output stderr warnings whenever a user uses mas until they set an environment variable or write to a config file to disable the warnings?

when used the way you don't want: I assume that issues caused by modified tabular formats would mainly occur when piping or redirecting output, but those are times users might be less likely to see the warnings if they are just written to a log. So is it simplest to just warn to stderr the same way for all uses (until the user has silenced the warnings)?

[MikeMcQuaid]

mas will include the JSON output option(s) (& possibly options to explicitly change the tabular output) in a minor release (presumably 1.9); changing the default tabular output will be left for a major release (presumably 2.0).

Ok, good to know, thanks.

The raw JSON won't be a maintained format by mas; it will just pass through Apple-sourced data as is.

Also helpful to know.

Do you mean output stderr warnings whenever a user uses mas until they set an environment variable or write to a config file to disable the warnings?
So is it simplest to just warn to stderr the same way for all uses (until the user has silenced the warnings)?

Yeh, that could work 👍🏻