From e0badc90e06aae8bbad183339adee2d3028fcc9a Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 24 Dec 2020 22:42:19 -0500 Subject: [PATCH 1/8] docs: add deprecate/disable/removal documentation --- ...ecating-Disabling-and-Removing-Formulae.md | 108 ++++++++++++++++++ docs/README.md | 1 + 2 files changed, 109 insertions(+) create mode 100644 docs/Deprecating-Disabling-and-Removing-Formulae.md diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md new file mode 100644 index 0000000000..cf445c1b9f --- /dev/null +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -0,0 +1,108 @@ +# Deprecating, Disabling, and Removing Formulae + +There are many reasons why formulae may be deprecated, disabled, or removed. This document explains the differences between each method as well as explaining when one method should be used over another. + +## Overview + +This general rule of thumb can be followed: + +- `deprecate!` should be used for formulae that should no longer be used +- `disable!` should be used for formulae that cannot be used +- Removal should be done with formulae that have been disabled for a long time or have a more serious issue + +## Deprecation + +If a user attempts to install a disabled formula, they will be shown a warning message but the install will succeed. + +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 be able to build from source and all bottles should continue to work. Users who choose to install deprecated formulae should not have any issues. + +The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived. + +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 +deprecate! date: "YYYY-MM-DD", because: :reason +``` + +The `date` parameter should be set to the date that the project became (or will become) deprecated. If there is no clear date but the formula needs to be deprecated, use today's date. If the `date` parameter is set to a date in the future, the formula will not become deprecated until that date. This can be useful if the upstream developers have indicated a date where the project will stop being supported. + +The `because` parameter can be set to a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. + +## Disabling + +If a user attempts to install a disabled formula, they will be shown an error message and the install will fail. + +A formula should be disabled to indicate to users that the formula cannot be used and may be removed in the future. Disabled formulae may not be able to build from source and may not have working bottles. Users who choose to attempt to install disabled formulae will likely run into issues. + +The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), has been deprecated for a long time, the upstream repository has been removed, or the project has license issues that are not compatible with homebrew/core. + +**Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** + +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 +disable! date: "YYYY-MM-DD", because: :reason +``` + +The `date` parameter should be set to the date that the reason for disabling came into effect. If there is no clear date but the formula needs to be disabled, use today's date. If the `date` parameter is set to a date in the future, the formula will be deprecated until that date (on which the formula will become disabled). + +The `because` parameter can be set to a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. + +## Removal + +A formula should be removed if there is a serious issue with the formula or the formula has been disabled for a long period of time. + +The most common reasons for removing are when the formula has a non-open-source license or when the formula has been disabled for over a year. + +## Deprecate and Disable Reasons + +When a formula is deprecated or disabled, a reason explaining the action should 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: + +- `:does_not_build`: the formulae that cannot be build from source +- `:no_license`: the formulae does not have a license +- `:repo_archived`: the upstream repository has been archived +- `:repo_removed`: the upstream repository has been removed +- `:unmaintained`: the project appears to be abandoned +- `:unsupported`: Homebrew's application of the software is not supported by the upstream developers (e.g. upstream only supports macOS version prior to 10.14) +- `:deprecated_upstream`: the project is deprecated upstream +- `:versioned_formula`: the formula is a versioned formula + +These reasons can be specified by their symbols (the comments show the message that will be displayed to users): + +```ruby +# Warning: has been deprecated because it is deprecated upstream! +deprecate! date: "2020-01-01", because: :deprecated_upstream +``` + +```ruby +# Error: has been disabled because it does not build! +disable! date: "2020-01-01", because: :does_not_build +``` + +If these pre-existing reasons do not fit, a custom reason can be specified. These reasons should be written to fit into the sentence ` has been deprecated/disabled because it !`. + +Here are examples of a well-worded custom reason: + +```ruby +# Warning: has been deprecated because it fetches unversioned dependencies at runtime! +deprecate! date: "2020-01-01", because: "fetches unversioned dependencies at runtime" +``` + +```ruby +# Error: has been disabled because it requires Python 2.7! +disable! date: "2020-01-01", because: "requires Python 2.7" +``` + +Here is an example of a poorly-worded custom reason: + +```ruby +# Warning: has been deprecated because it the formula fetches unversioned dependencies at runtime! +deprecate! date: "2020-01-01", because: "the formula fetches unversioned dependencies at runtime" +``` + +```ruby +# Error: has been disabled because it invalid license! +disable! date: "2020-01-01", because: "invalid license" +``` diff --git a/docs/README.md b/docs/README.md index f2240fef15..e079c9ac2d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,6 +40,7 @@ - [Acceptable Formulae](Acceptable-Formulae.md) - [License Guidelines](License-Guidelines.md) - [Formulae Versions](Versions.md) +- [Deprecating, Disabling, and Removing Formulae](Deprecating-Disabling-and-Removing-Formulae.md) - [Node for Formula Authors](Node-for-Formula-Authors.md) - [Python for Formula Authors](Python-for-Formula-Authors.md) - [Migrating A Formula To A Tap](Migrating-A-Formula-To-A-Tap.md) From 6739064a5e3dd8eac9b265d6e8ed26217fc5e174 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 24 Dec 2020 22:52:57 -0500 Subject: [PATCH 2/8] docs: clarity improvements to deprecate/disable/remove docs --- .../Deprecating-Disabling-and-Removing-Formulae.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index cf445c1b9f..3ea69ee80c 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -6,9 +6,9 @@ There are many reasons why formulae may be deprecated, disabled, or removed. Thi This general rule of thumb can be followed: -- `deprecate!` should be used for formulae that should no longer be used -- `disable!` should be used for formulae that cannot be used -- Removal should be done with formulae that have been disabled for a long time or have a more serious issue +- `deprecate!` should be used for formulae that _should_ no longer be used +- `disable!` should be used for formulae that _cannot_ be used +- Formulae that have been disabled for a long time or have a more serious issue should be removed ## Deprecation @@ -34,7 +34,7 @@ If a user attempts to install a disabled formula, they will be shown an error me A formula should be disabled to indicate to users that the formula cannot be used and may be removed in the future. Disabled formulae may not be able to build from source and may not have working bottles. Users who choose to attempt to install disabled formulae will likely run into issues. -The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), has been deprecated for a long time, the upstream repository has been removed, or the project has license issues that are not compatible with homebrew/core. +The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), has been deprecated for a long time, the upstream repository has been removed, or the project has no license. **Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** @@ -52,7 +52,9 @@ The `because` parameter can be set to a preset reason (using a symbol) or a cust A formula should be removed if there is a serious issue with the formula or the formula has been disabled for a long period of time. -The most common reasons for removing are when the formula has a non-open-source license or when the formula has been disabled for over a year. +A formula should be removed if it has been disabled for a long period of time, it has a non-open-source license, or there is another serious issue with the formula that makes it not compatible with homebrew/core. + +**Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** ## Deprecate and Disable Reasons @@ -65,7 +67,7 @@ There are two ways to indicate the reason. The preferred way is to use a pre-exi - `:repo_archived`: the upstream repository has been archived - `:repo_removed`: the upstream repository has been removed - `:unmaintained`: the project appears to be abandoned -- `:unsupported`: Homebrew's application of the software is not supported by the upstream developers (e.g. upstream only supports macOS version prior to 10.14) +- `:unsupported`: Homebrew's application of the software is not supported by the upstream developers (e.g. upstream only supports macOS versions prior to 10.14) - `:deprecated_upstream`: the project is deprecated upstream - `:versioned_formula`: the formula is a versioned formula From 361eb2711057be97113a865606a511c0fbff0304 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Fri, 25 Dec 2020 00:09:19 -0500 Subject: [PATCH 3/8] docs: fix some copy-and-paste mistakes Co-Authored-By: Carlo Cabrera <30379873+carlocab@users.noreply.github.com> --- docs/Deprecating-Disabling-and-Removing-Formulae.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index 3ea69ee80c..ba77e6e15a 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -12,7 +12,7 @@ This general rule of thumb can be followed: ## Deprecation -If a user attempts to install a disabled 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 succeed. 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 be able to build from source and all bottles should continue to work. Users who choose to install deprecated formulae should not have any issues. @@ -38,7 +38,7 @@ The most common reasons for disabling are when the formula cannot be built from **Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** -To deprecate a formula, add a `deprecate!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason: +To disable a formula, add a `disable!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason: ```ruby disable! date: "YYYY-MM-DD", because: :reason From 5a1adeae06a6660d43274e10bb60d5d14b7cd178 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Fri, 25 Dec 2020 11:00:58 -0500 Subject: [PATCH 4/8] docs: incorporate changes from code review Co-Authored-By: Seeker Co-Authored-By: Sean Molenaar Co-Authored-By: Mike McQuaid Co-Authored-By: Michka Popoff <3406519+iMichka@users.noreply.github.com> --- ...ecating-Disabling-and-Removing-Formulae.md | 38 +++++++------------ docs/Formula-Cookbook.md | 4 ++ 2 files changed, 17 insertions(+), 25 deletions(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index ba77e6e15a..c732aba6ac 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -6,15 +6,15 @@ There are many reasons why formulae may be deprecated, disabled, or removed. Thi This general rule of thumb can be followed: -- `deprecate!` should be used for formulae that _should_ no longer be used -- `disable!` should be used for formulae that _cannot_ be used -- Formulae that have been disabled for a long time or have a more serious issue should be removed +- `deprecate!` should be used for formulae that _should_ no longer be used. +- `disable!` should be used for formulae that _cannot_ be used. +- Formulae that have are not longer acceptable in homebrew/core or have been disabled for over a year should be removed. ## Deprecation If a user attempts to install a deprecated formula, they will be shown a warning message but the install will succeed. -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 be able to build from source and all bottles should continue to work. Users who choose to install deprecated formulae should not have any issues. +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 be able to build from source and their bottles should continue to work. The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived. @@ -24,7 +24,7 @@ To deprecate a formula, add a `deprecate!` call. This call should include a depr deprecate! date: "YYYY-MM-DD", because: :reason ``` -The `date` parameter should be set to the date that the project became (or will become) deprecated. If there is no clear date but the formula needs to be deprecated, use today's date. If the `date` parameter is set to a date in the future, the formula will not become deprecated until that date. This can be useful if the upstream developers have indicated a date where the project will stop being supported. +The `date` parameter should be set to the date that the project or version became (or will become) deprecated. If there is no clear date but the formula needs to be deprecated, use today's date. If the `date` parameter is set to a date in the future, the formula will not become deprecated until that date. This can be useful if the upstream developers have indicated a date where the project or version will stop being supported. The `because` parameter can be set to a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. @@ -32,7 +32,7 @@ The `because` parameter can be set to a preset reason (using a symbol) or a cust If a user attempts to install a disabled formula, they will be shown an error message and the install will fail. -A formula should be disabled to indicate to users that the formula cannot be used and may be removed in the future. Disabled formulae may not be able to build from source and may not have working bottles. Users who choose to attempt to install disabled formulae will likely run into issues. +A formula should be disabled to indicate to users that the formula cannot be used and will be removed in the future. Disabled formulae may no longer be able to build from source or have working bottles. The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), has been deprecated for a long time, the upstream repository has been removed, or the project has no license. @@ -50,20 +50,18 @@ The `because` parameter can be set to a preset reason (using a symbol) or a cust ## Removal -A formula should be removed if there is a serious issue with the formula or the formula has been disabled for a long period of time. - -A formula should be removed if it has been disabled for a long period of time, it has a non-open-source license, or there is another serious issue with the formula that makes it not compatible with homebrew/core. +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. **Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** ## Deprecate and Disable Reasons -When a formula is deprecated or disabled, a reason explaining the action should 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: +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): -- `:does_not_build`: the formulae that cannot be build from source -- `:no_license`: the formulae does not have a license +- `:does_not_build`: the formula cannot be built from source +- `:no_license`: the formula does not have a license - `:repo_archived`: the upstream repository has been archived - `:repo_removed`: the upstream repository has been removed - `:unmaintained`: the project appears to be abandoned @@ -85,24 +83,14 @@ disable! date: "2020-01-01", because: :does_not_build If these pre-existing reasons do not fit, a custom reason can be specified. These reasons should be written to fit into the sentence ` has been deprecated/disabled because it !`. -Here are examples of a well-worded custom reason: +A well-worded example of a custom reason would be: ```ruby # Warning: has been deprecated because it fetches unversioned dependencies at runtime! deprecate! date: "2020-01-01", because: "fetches unversioned dependencies at runtime" ``` -```ruby -# Error: has been disabled because it requires Python 2.7! -disable! date: "2020-01-01", because: "requires Python 2.7" -``` - -Here is an example of a poorly-worded custom reason: - -```ruby -# Warning: has been deprecated because it the formula fetches unversioned dependencies at runtime! -deprecate! date: "2020-01-01", because: "the formula fetches unversioned dependencies at runtime" -``` +A poorly-worded example of a custom reason would be: ```ruby # Error: has been disabled because it invalid license! diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 586c38dff6..ed744922b2 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -795,6 +795,10 @@ You can set environment variables in a formula's `install` method using `ENV["VA In summary, environment variables used by a formula need to conform to these filtering rules in order to be available. +### Deprecating and disabling a formula + +See our [Deprecating, Disabling, and Removing Formulae](Deprecating-Disabling-and-Removing-Formulae.md) documentation for more information about how and when to deprecate or disable a formula. + ## Updating formulae Eventually a new version of the software will be released. In this case you should update the [`url`](https://rubydoc.brew.sh/Formula#url-class_method) and [`sha256`](https://rubydoc.brew.sh/Formula#sha256%3D-class_method). If a [`revision`](https://rubydoc.brew.sh/Formula#revision%3D-class_method) line exists outside any `bottle do` block it should be removed. From b125bd92cf6cc4042716d499c816db89334d8b31 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Fri, 25 Dec 2020 12:13:38 -0500 Subject: [PATCH 5/8] docs: incorporate changes from code review Co-Authored-By: Carlo Cabrera <30379873+carlocab@users.noreply.github.com> --- docs/Deprecating-Disabling-and-Removing-Formulae.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index c732aba6ac..74824b48fa 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -8,13 +8,13 @@ This general rule of thumb can be followed: - `deprecate!` should be used for formulae that _should_ no longer be used. - `disable!` should be used for formulae that _cannot_ be used. -- Formulae that have are not longer acceptable in homebrew/core or have been disabled for over a year should be removed. +- Formulae that are no longer acceptable in homebrew/core or have been disabled for over a year should be removed. ## Deprecation If a user attempts to install a deprecated formula, they will be shown a warning message but the install will succeed. -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 be able to 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. The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived. @@ -26,15 +26,15 @@ deprecate! date: "YYYY-MM-DD", because: :reason The `date` parameter should be set to the date that the project or version became (or will become) deprecated. If there is no clear date but the formula needs to be deprecated, use today's date. If the `date` parameter is set to a date in the future, the formula will not become deprecated until that date. This can be useful if the upstream developers have indicated a date where the project or version will stop being supported. -The `because` parameter can be set to a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. +The `because` parameter can be a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. ## Disabling If a user attempts to install a disabled formula, they will be shown an error message and the install will fail. -A formula should be disabled to indicate to users that the formula cannot be used and will be removed in the future. Disabled formulae may no longer be able to build from source or have working bottles. +A formula should be disabled to indicate to users that the formula cannot be used and will be removed in the future. Disabled formulae may no longer build from source or have working bottles. -The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), has been deprecated for a long time, the upstream repository has been removed, or the project has no license. +The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), the formula has been deprecated for a long time, the upstream repository has been removed, or the project has no license. **Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** @@ -46,7 +46,7 @@ disable! date: "YYYY-MM-DD", because: :reason The `date` parameter should be set to the date that the reason for disabling came into effect. If there is no clear date but the formula needs to be disabled, use today's date. If the `date` parameter is set to a date in the future, the formula will be deprecated until that date (on which the formula will become disabled). -The `because` parameter can be set to a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. +The `because` parameter can be a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. ## Removal From 09132be32a163d83895081b0ddd02a314b4b54b6 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Sun, 27 Dec 2020 13:49:25 -0500 Subject: [PATCH 6/8] docs: use list for common disable reasons Co-Authored-By: Adrian Ho --- docs/Deprecating-Disabling-and-Removing-Formulae.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index 74824b48fa..20057f8a7e 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -34,7 +34,12 @@ If a user attempts to install a disabled formula, they will be shown an error me A formula should be disabled to indicate to users that the formula cannot be used and will be removed in the future. Disabled formulae may no longer build from source or have working bottles. -The most common reasons for disabling are when the formula cannot be built from source (meaning no bottles can be built), the formula has been deprecated for a long time, the upstream repository has been removed, or the project has no license. +The most common reasons for disabling a formula are: + +- it cannot be built from source (meaning no bottles can be built) +- it has been deprecated for a long time +- the upstream repository has been removed +- the project has no license **Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** From 5784e36ead31f94e46b102323d05ef20b841a0f5 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Mon, 28 Dec 2020 10:30:46 -0500 Subject: [PATCH 7/8] docs: improve clarity in deprecate/disable/removal docs Co-Authored-By: Mike McQuaid Co-Authored-By: Michka Popoff <3406519+iMichka@users.noreply.github.com> Co-Authored-By: Carlo Cabrera <30379873+carlocab@users.noreply.github.com> --- docs/Deprecating-Disabling-and-Removing-Formulae.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index 20057f8a7e..ee7bfd1b9a 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -12,9 +12,9 @@ This general rule of thumb can be followed: ## 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. @@ -55,15 +55,13 @@ The `because` parameter can be a preset reason (using a symbol) or a custom reas ## 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. - -**Note: disabled formulae in homebrew/core will be automatically removed one year after their disable date** +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. ## Deprecate and Disable Reasons 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 - `:no_license`: the formula does not have a license From 5f887ca934588a6add6b088eb652f4eaf0cb7bcc Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Mon, 28 Dec 2020 11:28:17 -0500 Subject: [PATCH 8/8] docs: clarify formula deprecation conditions Co-Authored-By: Mike McQuaid --- docs/Deprecating-Disabling-and-Removing-Formulae.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index ee7bfd1b9a..6261e71cd9 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -14,7 +14,7 @@ This general rule of thumb can be followed: 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. These formulae should continue to receive maintenance as needed to allow them to build. +A formula should be deprecated to indicate to users that the formula should not be used and will be disabled in the future. Deprecated formulae should be maintained by the Homebrew maintainers so they can still build from source and their bottles continue to work (even if unmaintained upstream). If this is not possible, they should be disabled. The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived.