disable!, deprecate!: add reason

[Rylan12]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

Resolves #8501

Add a reason for disabling and deprecating a formula. This means that the error that a user gets when trying to install one of these has more information and makes it easier to figure out what the problem is.

Example:

disable! because: "it cannot be built from source"

Right now, the because: parameter is optional. I plan on making it required by brew style, but I think we need to wait for the next release so that Homebrew/core formulae can accept the reason.

[MikeMcQuaid]

Right now, the because: parameter is optional. I plan on making it required by brew style, but I think we need to wait for the next release so that Homebrew/core formulae can accept the reason.

I'd also consider adding a commented-out odeprecated so we can deprecate it if it's not present on the next major/minor release, too.

[gromgit]

Can I suggest adding a pr: argument that specifies the PR# that did the deed, that outputs something like See https://github.com/homebrew/homebrew-core/pulls/X for details? Perhaps this can be injected automagically via CI?

[Rylan12]

I'd also consider adding a commented-out odeprecated so we can deprecate it if it's not present on the next major/minor release, too.

Good idea. Just to clarify, does that mean that we'll uncomment the line (deprecating it) when 2.5 is released and then remove the line for 2.6?

Can I suggest adding a pr: argument that specifies the PR# that did the deed, that outputs something like See https://github.com/homebrew/homebrew-core/pulls/X for details? Perhaps this can be injected automagically via CI?

Definitely like this idea. Not sure if CI can do it automatically (I'd be diving into some new territory there). If it can't, I could see this being a pain point because you don't easily know what PR number you'll get until you make it.

An alternative might be to query for PRs with the name <foo>: disable but I don't know how consistent we are with naming PRs.

[MikeMcQuaid]

Good idea. Just to clarify, does that mean that we'll uncomment the line (deprecating it) when 2.5 is released and then remove the line for 2.6?

Yup!

Can I suggest adding a pr: argument that specifies the PR# that did the deed, that outputs something like See https://github.com/homebrew/homebrew-core/pulls/X for details? Perhaps this can be injected automagically via CI?

CI can't do it automatically really and this would be a bit awkward to have to create a PR and then force push to it. It's also inviting people to jump on the PR and complain which I'm not sure is a good idea.

[gromgit]

I think the CI injection part can be skipped for now, since deprecation/disabling is rare enough that a quick edit/force-push shouldn't be too burdensome.

[MikeMcQuaid]

since deprecation/disabling is rare enough that a quick edit/force-push shouldn't be too burdensome.

I'd rather not put this onus on maintainers for something which I don't see as adding to the communication and gives people a bandwagon to be negative on.

[Rylan12]

I'd rather not put this onus on maintainers for something which I don't see as adding to the communication and gives people a bandwagon to be negative on.

Yeah, I agree. Plus, people can still find the PRs without too much trouble if they know where to look...

[MikeMcQuaid]

Thanks again @Rylan12!

[MikeMcQuaid]

Right now, the because: parameter is optional. I plan on making it required by brew style, but I think we need to wait for the next release so that Homebrew/core formulae can accept the reason.

@Rylan12 I've tagged 2.4.14 now and uncommented the deprecations in #8513 which (as expected) is causing a CI failure. If you could add these reasons en-masse to homebrew-core I can handle linuxbrew-core and the other taps. Cheers again, great work! ❤️

[Rylan12]

@MikeMcQuaid I've opened a PR for the disable! reasons at https://github.com/Homebrew/homebrew-core/pull/60321/files

Looking at the deprecate! reasons, though, I'm not sure it makes as much sense to require a reason. Most of the time, it looks like the reason would just be "it was deprecated upstream" or "it stopped being maintained". Should we still make this required?

Edit: there are more exceptions to this than I thought, so I think it's okay to keep the requirement. I'll open the PR and it can be discussed there

[MikeMcQuaid]

Looking at the deprecate! reasons, though, I'm not sure it makes as much sense to require a reason. Most of the time, it looks like the reason would just be "it was deprecated upstream" or "it stopped being maintained". Should we still make this required?

Edit: there are more exceptions to this than I thought, so I think it's okay to keep the requirement. I'll open the PR and it can be discussed there

Could provide symbols like with keg_only to be able to quickly specify a given, longer message?