asdf: add install instructions to caveats #54315
Conversation
Formula/asdf.rb
Outdated
| @@ -27,6 +28,20 @@ def install | |||
| prefix.install Dir["*"] | |||
| end | |||
|
|
|||
| def caveats | |||
| <<~EOS | |||
| In order to enable asdf, add the following to your .bash_profile or .zshrc | |||
There was a problem hiding this comment.
What does "enable" mean in this context? Because it works in the test below
There was a problem hiding this comment.
Executing the binary itself works, though for asdf to appear on your shell path and be used as intended, the asdf.sh script needs to be added to your shell config file.
We have in depth instructions on our site for the combination of OSs, Shell & installation method as there are many. It's probably better we just link to the docs instead of duplicating the instructions here.
There was a problem hiding this comment.
Anything that is definable in documentation is not supposed to be in caveats. Those are only for homebrew specific quirks or issues.
There was a problem hiding this comment.
Right, but the software itself isn't usable until external actions are taken, surely that's not a standard expectation of Homebrew users?
There was a problem hiding this comment.
That's why they're supposed to read the documentation of the tool they install.
There was a problem hiding this comment.
Should I show the message @jthegedus suggest?
to complete configuration of asdf, see the docs at https://asdf-vm.com/#/core-manage-asdf-vm
There was a problem hiding this comment.
I would prefer that than rehashing the various combinations here. Only one place for me to worry about keeping updated.
There was a problem hiding this comment.
If it's in upstream documentation it shouldn't be in the caveats. And since "read the docs here" isn't homebrew specific that shouldn't be in caveats either. (Other formula having something doesn't mean it's allowed)
There was a problem hiding this comment.
The caveat here is that there are steps after brew install. This is unlike the 99% of brew installed applications. I believe this fits well within the definition of caveat.
Since asdf is a multi-shell tool, the specific instructions for someone who installed via Homebrew are still a combination of the Shell they use, their specific Shell plugin manager, their OS and the versions of each of these. Far too much to include here and keep in sync with the changes in the core tool. The documentation site has dropdown menus which so users can clearly select the combination of their setup and get the correct instructions. It is most useful to direct users there to finish their setup.
There was a problem hiding this comment.
I've fixed my implementations to @jthegedus 's idea
Before doing my work, I looked for the right place to show some instructions on Homebrew Formula, then I found caveats is most suitable
asdf has an attribute to be configured by users, I believe this is one of core of asdf
Showing instructions is natural for this tool
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. |
|
No thanks stalebot |
|
@Homebrew/core I don't think this should be a caveat. Any other opinions? |
|
These are instructions, not caveats, sorry: https://rubydoc.brew.sh/Formula.html#caveats-instance_method |
|
This is a disappointing outcome. The Homebrew docs for caveats:
This package required further steps after running
These further instructions are specific to the installation via Homebrew itself. The fact they contain instructions for other package managers and OSs is irrelevant. |
|
A portable solution may be to show the relevant link/instructions or ask user permission to make the necessary configuration update automatically, if the configuration is incomplete when |
|
@HomeBrew/Core 1. Showing install instructions in
|
Since it is the homebrew policy to only print caveats that are unique to the homebrew install this is not irrelevant. I understand you want to help the user best you can but that should really be available in a nice document for everyone to read, not in the formula where it might become outdated over the years. I also recommend following @vszakats their suggestion since that would be able to tell the user this independent of the install method. |
I have invested significant effort into our Documentation site. I cannot help users who never go to the documentation. It appears that most of these users are Homebrew users. I believe this is the difference of user flows:
Before I will look for other solutions as we're just going in circles here. |
brew install --build-from-source <formula>, where<formula>is the name of the formula you're submitting?brew test <formula>, where<formula>is the name of the formula you're submitting?brew audit --strict <formula>(after doingbrew install <formula>)?