From c5070e2c7ed950de4bd136ed5c79f594b58dd81d Mon Sep 17 00:00:00 2001 From: Caleb Xu Date: Sat, 23 Nov 2024 21:03:25 -0500 Subject: [PATCH] docs: mention optional replacement parameter for deprecate/disable --- docs/Deprecating-Disabling-and-Removing-Casks.md | 12 ++++++++++++ docs/Deprecating-Disabling-and-Removing-Formulae.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/Deprecating-Disabling-and-Removing-Casks.md b/docs/Deprecating-Disabling-and-Removing-Casks.md index 396fb1a369..52a4987535 100644 --- a/docs/Deprecating-Disabling-and-Removing-Casks.md +++ b/docs/Deprecating-Disabling-and-Removing-Casks.md @@ -35,6 +35,12 @@ 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. + +```ruby +deprecate! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +``` + ## Disabling If a user attempts to install a disabled cask, they will be shown an error message and the install will fail. @@ -62,6 +68,12 @@ The `date` parameter should be set to the date that the reason for disabling cam 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. + +```ruby +disable! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +``` + ## Removal A cask should be removed if it does not meet our criteria for [acceptable casks](Acceptable-Casks.md) or has been disabled for over a year. diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index 5282a6ecbf..bd62b09b9c 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -37,6 +37,12 @@ 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. + +```ruby +deprecate! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +``` + ## Disabling If a user attempts to install a disabled formula, they will be shown an error message and the install will fail. @@ -64,6 +70,12 @@ The `date` parameter should be set to the date that the reason for disabling cam 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. + +```ruby +disable! date: "YYYY-MM-DD", because: :reason, replacement: "foo" +``` + ## 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 over a year.