Simplifying Homebrew terminology

jonchang commented 3 years ago

Provide a detailed description of the proposed feature

Homebrew should reduce the number of metaphors it uses in its user interface and documentation.

We currently demand that users internalize several metaphors when interacting with Homebrew. These include:

Formula (how to build a bit of software)
Bottle (pre-built software)
Cask (pre-built software on macOS)
Tap (a collection of software)
Keg (where software installs itself)
Cellar (where all my software install themselves)

As well as an additional number of less-common metaphors that contributors and maintainers need to know, like Rack, Tab, and Formulary.

I propose that we reduce the number of user-facing metaphors to Formula, Bottle, Cask, and Tap. That is to say, the output of any given brew command, and all documentation on docs.brew.sh, should avoid mentioning kegs or cellars. The only exception should be for maintainer-focused documentation and commands, and there the metaphors should only be used if they would otherwise cause unnecessary confusion.

What is the motivation for the feature?

As we no longer support commands like brew diy and brew switch, the Keg/Cellar/Formula distinction is unnecessarily confusing. Formula should only be "something I want to install" and the only additional bits of information users need to know about them is "where do I get it from" (Tap), "do I need to build it myself" (Bottle), and "will it be put in my PATH" (keg-only).

We can convey the information about whether something will be in their PATH without needing to introduce an entirely new metaphor for it. There is already a suitable metaphor we commonly use, and one that is more obvious for existing Terminal users: "linked". Note that the Cellar metaphor doesn't come up at all here, since the real path of where a bit of software is installed is arguably not relevant for users.

I therefore believe Keg and Cellar are less-useful concepts for users. The only need for those two terms, with respect to users, is whether some software they are interested in is linked into HOMEBREW_PREFIX or not. Asking users to learn two new metaphors for a feature that only provides one bit of information is unnecessary.

 % brew info openssl
-openssl@1.1: stable 1.1.1j (bottled) [keg-only]
+openssl@1.1: stable 1.1.1j (bottled) [unlinked]
 Cryptography and SSL/TLS Toolkit
 https://openssl.org/
-/usr/local/Cellar/openssl@1.1/1.1.1j (8,071 files, 18.5MB)
+/usr/local/opt/openssl@1.1 (1.1.1j, 8,071 files, 18.5MB)
   Poured from bottle on 2021-02-19 at 15:57:12
 From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openssl@1.1.rb
 License: OpenSSL
 ==> Caveats
 A CA file has been bootstrapped using certificates from the system
 keychain. To add additional certificates, place .pem files in
   /usr/local/etc/openssl@1.1/certs

 and run
   /usr/local/opt/openssl@1.1/bin/c_rehash

-openssl@1.1 is keg-only, which means it was not symlinked into /usr/local,
-because macOS provides LibreSSL.
-
+openssl@1.1 was not linked into /usr/local because macOS provides LibreSSL.
 If you need to have openssl@1.1 first in your PATH, run:
   echo 'export PATH="/usr/local/opt/openssl@1.1/bin:$PATH"' >> ~/.zshrc

 For compilers to find openssl@1.1 you may need to set:
   export LDFLAGS="-L/usr/local/opt/openssl@1.1/lib"
   export CPPFLAGS="-I/usr/local/opt/openssl@1.1/include"

 % brew unlink openssl
-Unlinking /usr/local/Cellar/openssl@1.1/1.1.1j... 0 symlinks removed.
+openssl@1.1 is already unlinked, because macOS provides LibreSSL.

How will the feature be relevant to at least 90% of Homebrew users?

Less cognitive load when learning and using Homebrew from novel metaphors.

What alternatives to the feature have been considered?

Retaining our currently terminology.

carlocab commented 3 years ago

I like the idea of simplifying terminology.

However, I think "keg-only" is one of the few pieces that don't need simplification. I've seen very little confusion about what exactly it means, most likely because it's already explained clearly in any instance where a user encounters it. That explanation is useful for users who go on to read formula files that say keg_only.

EricFromCanada commented 3 years ago

Another thing I've seen is how the word "formula" can refer to either the file itself (e.g. the contents of homebrew-/Formula/*), or what it installs in /usr/local/Cellar (aka Kegs) or as a general term encompassing both traditional formula files and cask files; each of which usually relies on context to distinguish.

Rylan12 commented 3 years ago

I'm definitely in favor of doing something like this. Tbh I still don't really understand why Formulary is called Formulary 😅

I'm torn about using keg-only vs unlinked. I think there's still a slight distinction between the two. keg-only means "unlinked by default" while unlinked, to me, just means "not linked due to either being keg-only or manually unlinking". So even if the terminology keg-only is dropped (which I would be fine with), I think it's still good to have that distinction.

Also, if keg-only is dropped, I think I'd push to deprecate and rename the keg_only formula DSL.

To me, the weird thing about Formula and Cask are that I see them as similar types of "things" (i.e. software) but their names don't quite fit the same analogy. To me, Formula makes me think "recipe for some software", so it seems like it should refer to the formula definition (i.e. the file). Cask, on the other hand, feels like a more physical object (i.e. the actual "finished product") seemingly referring to the installed application.

Documentation/messaging-wise, I think we can certainly use terms like "installed formula", "formula definition", "installed cask", and "cask definition" to help eliminate potential confusion. I don't think major code changes that rename classes and stuff are necessarily a good idea, though.

End of important stuff, no need to keep reading. I wrote the following and then realized it's not really useful to us unless we decide to re-make Homebrew and change a whole bunch of stuff, but figured I'd leave it in just because.

I guess if I were making Homebrew from scratch and needed to follow the beer theme, I'd make Formula refer to any software definition. Cask would then be a type of Formula that installs native apps, and something else would also be a type of Formula that refers to the software in the homebrew/homebrew-core repo. I'm not going to bother researching beer-related things to figure out what that should be, though, because it doesn't matter.

jonchang commented 3 years ago

I think this is one of the cases where if we could do a usability study it would help a lot in terms of figuring out what actually is confusing for users. Based on just what I see from the years of reading twitter, reddit, and the orange site, keg-only and cellar are the terms that cause the most confusion, followed by the formula vs cask distinction. I don't think there's a whole lot we can do for the latter but certainly for the former we can simplify things.

Another thing I've seen is how the word "formula" can refer to either the file itself (e.g. the contents of homebrew-/Formula/*), or what it installs in /usr/local/Cellar (aka Kegs) or as a general term encompassing both traditional formula files and cask files; each of which usually relies on context to distinguish.

My idea for this would be to simply drop the use of "formula" to refer to the file on disk (=build recipe) and instead use the proposed definition in the original issue ("something I want to install"). Older terminology that's mostly been excised from the codebase refers to "software built from a Formula (=build recipe)" as "brews", in the sense that "brews that homebrew distributes" (=bottles), but I don't really want to revive that since that only increases confusion.

I'm torn about using keg-only vs unlinked. I think there's still a slight distinction between the two. keg-only means "unlinked by default" while unlinked, to me, just means "not linked due to either being keg-only or manually unlinking". So even if the terminology keg-only is dropped (which I would be fine with), I think it's still good to have that distinction.

This is basically what I'm proposing -- the only info that "keg-only" provides is linked by default vs not linked by default. We can convey this knowledge without introducing jargon like keg-only. We can do this because (to my knowledge) the links present in /usr/local/opt stay there even if you run brew unlink wget for example.

To me, the weird thing about Formula and Cask are that I see them as similar types of "things" (i.e. software) but their names don't quite fit the same analogy. To me, Formula makes me think "recipe for some software", so it seems like it should refer to the formula definition (i.e. the file). Cask, on the other hand, feels like a more physical object (i.e. the actual "finished product") seemingly referring to the installed application.

Yeah, the formula <-> bottle <-> cask distinction is extremely confusing as both bottle and cask are talking about binary redistributions of software, but they are very different in practice.

reitermarkus commented 3 years ago

Documentation/messaging-wise, I think we can certainly use terms like "installed formula", "formula definition", "installed cask", and "cask definition" to help eliminate potential confusion. I don't think major code changes that rename classes and stuff are necessarily a good idea, though.

What is also quite confusing is that we actually have a distinction between “formula definition” (Formula) and “installed formula” (Keg) in code but for casks both use the Cask class.

MikeMcQuaid commented 3 years ago

Tbh I still don't really understand why Formulary is called Formulary 😅

A factory for formula.

I'm torn about using keg-only vs unlinked. I think there's still a slight distinction between the two. keg-only means "unlinked by default" while unlinked, to me, just means "not linked due to either being keg-only or manually unlinking". So even if the terminology keg-only is dropped (which I would be fine with), I think it's still good to have that distinction.

Agreed.

To me, the weird thing about Formula and Cask are that I see them as similar types of "things" (i.e. software) but their names don't quite fit the same analogy. To me, Formula makes me think "recipe for some software", so it seems like it should refer to the formula definition (i.e. the file). Cask, on the other hand, feels like a more physical object (i.e. the actual "finished product") seemingly referring to the installed application.

I think it would be good to have a name we use consistently when we describe both e.g. "package".

Despite the (brilliant) write up by @jonchang I'm mildly 👎🏻 on this. I think the ship has somewhat sailed here and we run a risk of further confusing people by removing the keg/cellar metaphors. I feel more strongly about not removing references to "cellar" than "keg" because the prior is literally the name of a location on disk.

That is to say, the output of any given brew command, and all documentation on docs.brew.sh, should avoid mentioning kegs or cellars. The only exception should be for maintainer-focused documentation and commands, and there the metaphors should only be used if they would otherwise cause unnecessary confusion.

A middle ground I'd be neutral (maybe even positive if you catch me on a really good day) rather than 👎🏻 on would be removing them from all end-user documentation focused and commands but keeping them in all contributor/developer documentation and commands.

saxbophone commented 3 years ago

As someone for whom all the beer-related metaphors have been more of a hindrance than an aid to understanding, I support this suggestion.

MikeMcQuaid commented 3 years ago

As someone for whom all the beer-related metaphors have been more of a hindrance than an aid to understanding

We're not proposing changing these metaphors.

MikeMcQuaid commented 2 years ago

This has been over a year with no movement so we're gonna pass for now. Thanks for the discussion, all.

Homebrew / brew