Merge pull request #18810 from alebcay/deprecate-disable-replacement-docs

docs: mention optional replacement parameter for deprecate/disable

Author: MikeMcQuaid

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.

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.