asdf: add install instructions to caveats

[januswel]

• Have you followed the guidelines for contributing?
• Have you checked that there aren't other open pull requests for the same formula update/change?
• Have you built your formula locally with brew install --build-from-source <formula>, where <formula> is the name of the formula you're submitting?
• Is your test running fine brew test <formula>, where <formula> is the name of the formula you're submitting?
• Does your build pass brew audit --strict <formula> (after doing brew install <formula>)?

---

[jthegedus]

I did not know this was a thing, this is great! Perhaps add a link to the docs site as the specific combinations of each shell are difficult to cover.

[SMillerDev]

What does "enable" mean in this context? Because it works in the test below

[jthegedus]

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.

[SMillerDev]

Anything that is definable in documentation is not supposed to be in caveats. Those are only for homebrew specific quirks or issues.

[jthegedus]

Right, but the software itself isn't usable until external actions are taken, surely that's not a standard expectation of Homebrew users?

[SMillerDev]

That's why they're supposed to read the documentation of the tool they install.

[januswel]

Should I show the message @jthegedus suggest?

to complete configuration of asdf, see the docs at https://asdf-vm.com/#/core-manage-asdf-vm

[jthegedus]

I would prefer that than rehashing the various combinations here. Only one place for me to worry about keeping updated.

[SMillerDev]

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)

[jthegedus]

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.

[januswel]

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

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[jthegedus]

No thanks stalebot

[SMillerDev]

@Homebrew/core I don't think this should be a caveat. Any other opinions?

[MikeMcQuaid]

These are instructions, not caveats, sorry: https://rubydoc.brew.sh/Formula.html#caveats-instance_method

[jthegedus]

This is a disappointing outcome.

The Homebrew docs for caveats:

Warn the user about any Homebrew-specific issues or quirks for this package These should not contain setup instructions that would apply to installation through a different package manager on a different OS.

Warn the user about any Homebrew-specific issues or quirks for this package

This package required further steps after running brew install, seems very specific to Homebrew and a quirk of this package.

These should not contain setup instructions that would apply to installation through a different package manager on a different OS.

These further instructions are specific to the installation via Homebrew itself. The fact they contain instructions for other package managers and OSs is irrelevant.

[vszakats]

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 asdf is executed by the user.

[januswel]

@HomeBrew/Core
I believe the place to show install instructions is needed and nothing is born from denial.
I think we have 2 options.

1. Showing install instructions in #caveats

This PR.

2. Showing install instructions in #install

Is it OK to show instructions in the following method?

https://rubydoc.brew.sh/Formula.html#install-instance_method

3. Implement install steps in #install

This is impossible to complete.
We can't define the result of installation, because every user needs different configurations for their sh settings
You wouldn't like it if some software changed your .bashrc / .zshrc etc, would you?

[SMillerDev]

The fact they contain instructions for other package managers and OSs is irrelevant.

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.

[jthegedus]

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 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:

• hombrew users
  • hear about asdf
  • brew install asdf
  • not working 🤔 I'll report a GitHub issue
  • GitHub issue is created
• non-homebrew users:
  • hear about asdf
  • go to GitHub and are linked to the Docs site
  • install asdf as per docs

Before asdf is functional your shell config needs to be updated. Given we support many shells and shell configs are very custom we require the users to update their config manually, as most similar tools do.

I will look for other solutions as we're just going in circles here.