diff --git a/docs/Deprecating-Disabling-and-Removing-Casks.md b/docs/Deprecating-Disabling-and-Removing-Casks.md index 9e89ae14b3..375e19ed53 100644 --- a/docs/Deprecating-Disabling-and-Removing-Casks.md +++ b/docs/Deprecating-Disabling-and-Removing-Casks.md @@ -1,5 +1,5 @@ --- -last_review_date: "1970-01-01" +last_review_date: 2025-05-15 --- # Deprecating, Disabling and Removing Casks @@ -10,9 +10,9 @@ There are many reasons why casks may be deprecated, disabled or removed. This do These general rules of thumb can be followed: -- `deprecate!` should be used for casks that _should_ no longer be used. -- `disable!` should be used for casks that _cannot_ be used. -- Casks that are no longer acceptable in `homebrew/cask` or have been disabled for over a year _should_ be removed. +1. `deprecate!` should be used for casks that _should_ no longer be used. +2. `disable!` should be used for casks that _cannot_ be used. +3. Casks that are no longer acceptable in `homebrew/cask` or have been disabled for over a year _should_ be removed. ## Deprecation @@ -24,10 +24,10 @@ The most common reasons for deprecation are when the upstream project is depreca Casks should only be deprecated if at least one of the following are true: -- the software installed by the cask cannot be run on any of our supported macOS versions +- the software installed by the cask cannot be run on any supported OS versions - the cask has outstanding CVEs - the cask has [zero installs in the last 90 days](https://formulae.brew.sh/analytics/cask-install/90d/) -- the software installed by the cask has been discontinued upstream +- the software installed by the cask has been discontinued or abandoned upstream To deprecate a cask, add a `deprecate!` call. This call should include a deprecation date in the ISO 8601 format and a deprecation reason: @@ -39,43 +39,43 @@ The `date` parameter should be set to the date that the deprecation period shoul 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. -An optional `replacement` parameter may also be specified to suggest a replacement formula or cask to the user. The value of the parameter is a string. +An optional `replacement_formula` or `replacement_cask` parameter may also be specified to suggest a replacement formula or cask to the user. The value of the parameter is a string. ```ruby -deprecate! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +deprecate! date: "YYYY-MM-DD", because: :reason, replacement_formula: "foo" ``` ## Disabling If a user attempts to install a disabled cask, they will be shown an error message and the install will fail. -A cask should be disabled to indicate to users that the cask cannot be used and will be removed in the future. Disabled cask are those that could not be installed successfully any longer. +A cask should be disabled to indicate to users that the cask cannot be used and will be removed in the future. Disabled casks are those that can no longer be successfully installed. The most common reasons for disabling a cask are: -- it cannot be installed on any of our supported macOS versions +- it cannot be installed on any supported OS versions - it has been deprecated for a long time - the upstream URL has been removed -Popular casks (e.g. have more than 300 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/cask-install/90d/)) should not be disabled without a deprecation period of at least six months unless they cannot be installed on all macOS versions and issue is unable be fixed (e.g. download URL no longer works and a mirror cannot be sourced). +Popular casks (e.g. have more than 300 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/cask-install/90d/)) should not be disabled without a deprecation period of at least six months unless they cannot be installed on any supported OS versions and the issue is unfixable (e.g. download URL no longer works and a mirror cannot be sourced). -Unpopular casks (e.g. have fewer than 300 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/cask-install/90d/)) can be disabled immediately for any of the reasons above. +Unpopular casks (e.g. have fewer than 300 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/cask-install/90d/)) can be disabled immediately for any of the reasons above, e.g. the upstream URL has been removed. They can be manually removed three months after their disable date. -To disable a cask, add a `disable!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason: +To disable a cask, 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 ``` -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 cask needs to be disabled, use today's date. If the `date` parameter is set to a date in the future, the cask will be deprecated until that date (on which the cask will become disabled). +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 cask needs to be disabled, use today's date. If the `date` parameter is set to a date in the future, the cask will be deprecated until that date (upon which the cask will become disabled). 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. -Similar to deprecated casks, an optional `replacement` parameter may also be specified for disabled casks to suggest a replacement formula or cask to the user. The value of the parameter is a string. +Similar to deprecated casks, an optional `replacement_formula` or `replacement_cask` parameter may also be specified for disabled casks to suggest a replacement formula or cask to the user. The value of the parameter is a string. ```ruby -disable! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +disable! date: "YYYY-MM-DD", because: :reason, replacement_cask: "foo" ``` ## Removal @@ -88,11 +88,14 @@ A cask should be removed if it does not meet our criteria for [acceptable casks] When a cask 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://github.com/Homebrew/brew/blob/master/Library/Homebrew/deprecate_disable.rb): +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): - `:discontinued`: the cask is discontinued upstream +- `:moved_to_mas`: the cask is now exclusively distributed on the Mac App Store - `:no_longer_available`: the cask is no longer available upstream +- `:no_longer_meets_criteria`: the cask no longer meets the criteria for acceptable casks - `:unmaintained`: the cask is not maintained upstream +- `:unsigned`: the cask is unsigned or does not meet signature requirements These reasons can be specified by their symbols (the comments show the message that will be displayed to users): diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index de34a93582..1168076645 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -1,5 +1,5 @@ --- -last_review_date: "1970-01-01" +last_review_date: 2025-05-15 --- # Deprecating, Disabling and Removing Formulae @@ -10,9 +10,9 @@ There are many reasons why formulae may be deprecated, disabled or removed. This These general rules 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 are no longer acceptable in `homebrew/core` or have been disabled for over a year _should_ be removed. +1. `deprecate!` should be used for formulae that _should_ no longer be used. +2. `disable!` should be used for formulae that _cannot_ be used. +3. Formulae that are no longer acceptable in `homebrew/core` or have been disabled for over a year _should_ be removed. ## Deprecation @@ -20,18 +20,18 @@ If a user attempts to install a deprecated formula, they will be shown a warning 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 continue to be maintained by the Homebrew maintainers so they 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. +The most common reasons for deprecation are when the upstream project is deprecated, unmaintained or archived. Formulae should only be deprecated if at least one of the following are true: -- the formula does not build on any of our supported macOS versions and on Linux +- the formula does not build on any supported OS versions - the formula has outstanding CVEs - the formula has [zero installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/) - the software installed by the formula has been discontinued or abandoned upstream -Formulae with dependents should not be deprecated until or when all dependents are also deprecated. +Formulae with dependents should not be deprecated unless all dependents are also deprecated. -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 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 @@ -41,10 +41,10 @@ The `date` parameter should be set to the date that the deprecation period shoul 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. -An optional `replacement` parameter may also be specified to suggest a replacement formula or cask to the user. The value of the parameter is a string. +An optional `replacement_formula` or `replacement_cask` parameter may also be specified to suggest a replacement formula or cask to the user. The value of the parameter is a string. ```ruby -deprecate! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +deprecate! date: "YYYY-MM-DD", because: :reason, replacement_formula: "foo" ``` ## Disabling @@ -55,13 +55,13 @@ A formula should be disabled to indicate to users that the formula cannot be use The most common reasons for disabling a formula are: -- it cannot be built from source on all supported OS versions (meaning no new bottles can be built) +- it cannot be built from source on any supported OS versions (meaning no new bottles can be built) - it has been deprecated for a long time - the project has no license Popular formulae (e.g. have more than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) should not be disabled without a deprecation period of at least six months even if e.g. they do not build from source and do not have a license. -Unpopular formulae (e.g. have fewer than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) can be disabled immediately for any of the reasons above e.g. they cannot be built from source on any supported macOS version or Linux. +Unpopular formulae (e.g. have fewer than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) can be disabled immediately for any of the reasons above, e.g. they cannot be built from source on any supported macOS version or Linux. They can be manually removed three months 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: @@ -70,14 +70,14 @@ To disable a formula, add a `disable!` call. This call should include a deprecat 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 `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 (upon which the formula will become disabled). 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. -Similar to deprecated formulae, an optional `replacement` parameter may also be specified for disabled formulae to suggest a replacement formula or cask to the user. The value of the parameter is a string. +Similar to deprecated formulae, an optional `replacement_formula` or `replacement_cask` parameter may also be specified for disabled formulae to suggest a replacement formula or cask to the user. The value of the parameter is a string. ```ruby -disable! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +disable! date: "YYYY-MM-DD", because: :reason, replacement_cask: "foo" ``` ## Removal @@ -90,13 +90,13 @@ A formula should be removed if it does not meet our criteria for [acceptable for 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://github.com/Homebrew/brew/blob/master/Library/Homebrew/deprecate_disable.rb): +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): - `:does_not_build`: the formula cannot be built from source on any supported macOS version or Linux. - `:no_license`: we cannot identify a license for the formula - `:repo_archived`: the upstream repository has been archived and no replacement is pointed to that we can use - `:repo_removed`: the upstream repository has been removed and no replacement is mentioned on the homepage that we can use -- `:unmaintained`: the project appears to be abandoned i.e. it has had no commits for at least a year and has critical bugs or CVE that have been reported and gone resolved longer. Note: some software is "done"; a lack of activity does not imply a need for removal. +- `:unmaintained`: the project appears to be abandoned, i.e. it has had no commits for at least a year and has critical bugs or CVEs that have been reported and left unresolved for longer. **Note:** some software is "done"; a lack of activity does not imply a need for removal. - `:unsupported`: Homebrew's compilation of the software is not supported by the upstream developers (e.g. upstream only supports macOS versions older than 10.15) - `:deprecated_upstream`: the project is deprecated upstream and no replacement is pointed to that we can use - `:versioned_formula`: the formula is a versioned formula and no longer [meets the requirements](Versions.md).