mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve clarity in deprecate/disable/removal docs

Browse Source 
Co-Authored-By: Mike McQuaid <mike@mikemcquaid.com>
Co-Authored-By: Michka Popoff <3406519+iMichka@users.noreply.github.com>
Co-Authored-By: Carlo Cabrera <30379873+carlocab@users.noreply.github.com>
This commit is contained in:
Rylan Polster 2020-12-28 10:30:46 -05:00
parent 09132be32a
commit 5784e36ead
1 changed files with 4 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -12,9 +12,9 @@ This general rule of thumb can be followed:
## Deprecation ## Deprecation
If a user attempts to install a deprecated formula, they will be shown a warning message but the install will succeed. If a user attempts to install a deprecated formula, they will be shown a warning message but the install will proceed.
A formula should be deprecated to indicate to users that the formula should not be used and may be disabled in the future. Deprecated formulae should still build from source and their bottles should continue to work. A formula should be deprecated to indicate to users that the formula should not be used and may be disabled in the future. Deprecated formulae should still build from source and their bottles should continue to work. These formulae should continue to receive maintenance as needed to allow them to build.
The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived. The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived.
@ -55,15 +55,13 @@ The `because` parameter can be a preset reason (using a symbol) or a custom reas
## Removal ## Removal
A formula should be removed if it does not meet our criteria for [acceptable formulae](Acceptable-Formulae.md) or [versioned formulae](Versions.md), has a non-open-source license, or has been disabled for a long period of time. A formula should be removed if it does not meet our criteria for [acceptable formulae](Acceptable-Formulae.md) or [versioned formulae](Versions.md), has a non-open-source license, or has been disabled for over a year.
**Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date**
## Deprecate and Disable Reasons ## Deprecate and Disable Reasons
When a formula is deprecated or disabled, a reason explaining the action must be provided. When a formula is deprecated or disabled, a reason explaining the action must be provided.
There are two ways to indicate the reason. The preferred way is to use a pre-existing symbol to indicate the reason. The available symbols are listed below and can be found in the [`DeprecateDisable` module](https://rubydoc.brew.sh/DeprecateDisable.html#DEPRECATE_DISABLE_REASONS-constant): There are two ways to indicate the reason. The preferred way is to use a pre-existing symbol to indicate the reason. The available symbols are listed below and can be found in the [`DeprecateDisable` module](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/deprecate_disable.rb):
- `:does_not_build`: the formula cannot be built from source - `:does_not_build`: the formula cannot be built from source
- `:no_license`: the formula does not have a license - `:no_license`: the formula does not have a license