Add caveats-like field for less important notes?

[phinze]

Over in #8915 we had to turn away a PR because @ndr-qef and @vitorgalvao agreed that caveats should be reserved for more critical notices about the install rather than helpful recommendations.

It seems to me that we should be able to welcome contributions with helpful recommendations for software use (provided the notes are not overly long or user-specific).

In my mind we have three options here. We could:

• Agree to loosen the definition of what can go in caveats to accept stuff like this
• Add a new field for recommendations or notes
• Decide that we don't want recommendations of this nature in Casks

I don't feel incredibly strongly, so I'm willing to be convinced that any of these three is the best move. I wanted to have the conversation though. Thoughts?

[vitorgalvao]

My biggest issue with non-critical messages in caveats is the more messages we output, the more they all blend and the sooner they’ll start to be ignored. There are some messages that really need to be shown for the experience to not be broken, and if we start to blend many optional suggestions there, users will start to ignore the important ones as well.

I believe the sentiment when a caveat goes by and you missed it should be “wait, what was that? I should go back and check”, and never “wait, what was that? Meh, probably nothing important”.

[phinze]

Yeah that's a good point. Perhaps we could address that with display tweaking? Or maybe we just shrug and punt for now. Will wait for other @caskroom/maintainers to weigh in.

[alebcay]

I feel that color coding would help mitigate the issue, but if there's a lot of output, that in itself may not be enough.

I know that Homebrew also has a lesser-used Warning field (which is red output and underlined). I think it's used internally by the Homebrew system and cannot be called from inside Formulae.

Lastly, I propose a flag or environment variable (or later, once a config file system is implemented, possibly a setting there) that toggles the verbosity of output (while we already have -v, it seems that a simple "on/off" switch for verbosity may not suffice). Or, if a new field for recommendations and what not is implemented, make it only show when -v is specified.

[vitorgalvao]

I don’t see much problem with that solution (adding an extra flag). Even if it is something you can set in HOMEBREW_CASK_OPTS, if you specifically have to do it then you’re likely the type of person that wants and reads everything anyway. Not sure it’s worth the extra complexity, but it definitely mitigates my previous concern.

[tapeinosyne]

I am fairly adamant that caveats should remain caveats: warnings to be heeded, lest woe betide you. It is good UX to distinguish the “must” from the “may”.

On the subject of usage recommendations, I feel conservative. The convenience is desirable, but they would be a blob of freeform information which:

• we are expected to guarantee to some degree;
• will invariably be inconsistent across casks;
• may provide little benefit over a web search.

From the perspective of brew cask as a CLI utility, I worry that storing a compendium of facts in the caskbase would become sprawl. Perhaps the concern of recommendations would be best addressed by an external command akin to Homebrew's brew-desc.

[rolandwalker]

The worry about sprawl makes sense to me, the worry about consistency across Casks less so.

As for a theoretical interface for notes, consider a distinct verb instead of an option/environment var. zap is just an uninstall that only runs when explicitly requested. Similarly a notes stanza could be implemented as a caveats that only runs when you invoke brew cask notes.

Incidentally, I would have kept the specific caveat in #8915, because it is a soft dependency. (It would be nice to support soft dependencies in the future along with a --with-extras flag.) Though you are right that it is poor UX. Maybe it should be better kept as a comment.

[vitorgalvao]

We should likely not focus on #8915 too much for this, though. All I can see when I look at it is :optional and :recommended, meaning there is a way better (and currently unimplemented) way to solve it. Current caveats I feel are relevant to this discussion include:

• springy.rb and candybar (these could warrant a special caveat option, as it is not extremely uncommon — there are a few more cask which similarly have a free license, in caskroom/versions)
• p4merge
• jenkins (a section of)
• diffmerge
• dewdrop

Found a bunch more, but the ones not included seem to me to be so useless they should be outright removed. Will submit PRs for those.

[rolandwalker]

Another example of a note or hack just turned up in #8202 (comment) .

This particular item looks like it should not be a default, but it is darn helpful to include it somehow.

[tapeinosyne]

The worry about sprawl makes sense to me, the worry about consistency across Casks less so.

To be clear, my concern is not quality or quantity, but modes of action. I would not be overly fond of a CLI which intersperses explanatory text, shell commands, other tools, and links to be opened in a browser.