admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Update documentation on deprecating and disabling formulae

Browse Source 
This is based on the discussion at Homebrew/homebrew-core#91368.

A few reasons why we don't want to deprecate formulae that have
dependents:

1. This results in displaying warning messages to (at least some) users
   that they can't do anything about.
2. `test-bot` does not test deprecated formulae, so we risk breaking
   dependent formulae when one of its dependencies is not tested.
3. It is much harder to commit to a disable date for formulae with
   dependents because we don't know when we'll be able to wean
   dependents off of a deprecated formula.

I think it's important to have a disable date in mind when we deprecate
formulae. Otherwise, we might end up leaving formulae deprecated
indefinitely. This is bad because it teaches users to not take
deprecation warnings seriously.
This commit is contained in:
Carlo Cabrera 2022-01-16 00:43:41 +08:00
parent 069ab087f9
commit 6214ce3024
No known key found for this signature in database
GPG Key ID: C74D447FC549A1D0
1 changed files with 7 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/Deprecating-Disabling-and-Removing-Formulae.md
View File

@ -18,6 +18,11 @@ A formula should be deprecated to indicate to users that the formula should not
The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived.
Formulae with dependents should **not** be deprecated unless the formula:
- does not build on any of our supported platforms; or,
- has outstanding CVEs.
To deprecate a formula, add a `deprecate!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason:
```ruby
@ -41,6 +46,8 @@ The most common reasons for disabling a formula are:
- the upstream repository has been removed
- the project has no license
Formulae should not be disabled without a reasonable deprecation period unless the circumstances are exceptional (e.g. the formula does not build). How long a reasonable period is depends on the formula's usage statistics. Popular formulae should have longer deprecation periods. We should aim to have a formula deprecated for at least three months before disabling it.
**Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date**
To disable a formula, add a `disable!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason: