deprecate_disable: support optional replacement parameter

Library/Homebrew/cask/cask.rb

@@ -363,38 +363,40 @@
 
     def to_h
       {
-        "token"                => token,
-        "full_token"           => full_name,
-        "old_tokens"           => old_tokens,
-        "tap"                  => tap&.name,
-        "name"                 => name,
-        "desc"                 => desc,
-        "homepage"             => homepage,
-        "url"                  => url,
-        "url_specs"            => url_specs,
-        "version"              => version,
-        "installed"            => installed_version,
-        "installed_time"       => install_time&.to_i,
-        "bundle_version"       => bundle_long_version,
-        "bundle_short_version" => bundle_short_version,
-        "outdated"             => outdated?,
-        "sha256"               => sha256,
-        "artifacts"            => artifacts_list,
-        "caveats"              => (caveats unless caveats.empty?),
-        "depends_on"           => depends_on,
-        "conflicts_with"       => conflicts_with,
-        "container"            => container&.pairs,
-        "auto_updates"         => auto_updates,
-        "deprecated"           => deprecated?,
-        "deprecation_date"     => deprecation_date,
-        "deprecation_reason"   => deprecation_reason,
-        "disabled"             => disabled?,
-        "disable_date"         => disable_date,
-        "disable_reason"       => disable_reason,
-        "tap_git_head"         => tap_git_head,
-        "languages"            => languages,
-        "ruby_source_path"     => ruby_source_path,
-        "ruby_source_checksum" => ruby_source_checksum,
+        "token"                   => token,
+        "full_token"              => full_name,
+        "old_tokens"              => old_tokens,
+        "tap"                     => tap&.name,
+        "name"                    => name,
+        "desc"                    => desc,
+        "homepage"                => homepage,
+        "url"                     => url,
+        "url_specs"               => url_specs,
+        "version"                 => version,
+        "installed"               => installed_version,
+        "installed_time"          => install_time&.to_i,
+        "bundle_version"          => bundle_long_version,
+        "bundle_short_version"    => bundle_short_version,
+        "outdated"                => outdated?,
+        "sha256"                  => sha256,
+        "artifacts"               => artifacts_list,
+        "caveats"                 => (caveats unless caveats.empty?),
+        "depends_on"              => depends_on,
+        "conflicts_with"          => conflicts_with,
+        "container"               => container&.pairs,
+        "auto_updates"            => auto_updates,
+        "deprecated"              => deprecated?,
+        "deprecation_date"        => deprecation_date,
+        "deprecation_reason"      => deprecation_reason,
+        "deprecation_replacement" => deprecation_replacement,
+        "disabled"                => disabled?,
+        "disable_date"            => disable_date,
+        "disable_reason"          => disable_reason,
+        "disable_replacement"     => disable_replacement,
+        "tap_git_head"            => tap_git_head,
+        "languages"               => languages,
+        "ruby_source_path"        => ruby_source_path,
+        "ruby_source_checksum"    => ruby_source_checksum,
       }
     end
 
@@ -415,11 +417,13 @@
       if deprecation_date
         api_hash["deprecation_date"] = deprecation_date
         api_hash["deprecation_reason"] = deprecation_reason
+        api_hash["deprecation_replacement"] = deprecation_replacement
       end
 
       if disable_date
         api_hash["disable_date"] = disable_date
         api_hash["disable_reason"] = disable_reason
+        api_hash["disable_replacement"] = disable_replacement
       end
 
       if (url_specs_hash = url_specs).present?

Library/Homebrew/cask/cask.rbi

@@ -26,12 +26,16 @@ module Cask
 
     def deprecation_reason; end
 
+    def deprecation_replacement; end
+
     def disabled?; end
 
     def disable_date; end
 
     def disable_reason; end
 
+    def disable_replacement; end
+
     def homepage; end
 
     def language; end

Library/Homebrew/cask/dsl.rb

@@ -87,10 +87,12 @@
       :deprecated?,
       :deprecation_date,
       :deprecation_reason,
+      :deprecation_replacement,
       :disable!,
       :disabled?,
       :disable_date,
       :disable_reason,
+      :disable_replacement,
       :discontinued?, # TODO: remove once discontinued? is removed (4.5.0)
       :livecheck,
       :livecheckable?,
@@ -105,8 +107,8 @@
     extend Attrable
     include OnSystem::MacOSOnly
 
-    attr_reader :cask, :token, :deprecation_date, :deprecation_reason, :disable_date, :disable_reason,
-                :on_system_block_min_os
+    attr_reader :cask, :token, :deprecation_date, :deprecation_reason, :deprecation_replacement, :disable_date,
+                :disable_reason, :disable_replacement, :on_system_block_min_os
 
     attr_predicate :deprecated?, :disabled?, :livecheckable?, :on_system_blocks_exist?, :depends_on_set_in_block?
 
@@ -442,11 +444,12 @@
     # NOTE: A warning will be shown when trying to install this cask.
     #
     # @api public
-    def deprecate!(date:, because:)
+    def deprecate!(date:, because:, replacement: nil)
       @deprecation_date = Date.parse(date)
       return if @deprecation_date > Date.today
 
       @deprecation_reason = because
+      @deprecation_replacement = replacement
       @deprecated = true
     end
 
@@ -455,16 +458,18 @@
     # NOTE: An error will be thrown when trying to install this cask.
     #
     # @api public
-    def disable!(date:, because:)
+    def disable!(date:, because:, replacement: nil)
       @disable_date = Date.parse(date)
 
       if @disable_date > Date.today
         @deprecation_reason = because
+        @deprecation_replacement = replacement
         @deprecated = true
         return
       end
 
       @disable_reason = because
+      @disable_replacement = replacement
       @disabled = true
     end
 

Library/Homebrew/cask/info.rb

@@ -12,7 +12,10 @@
       output = "#{title_info(cask)}\n"
       output << "#{Formatter.url(cask.homepage)}\n" if cask.homepage
       deprecate_disable = DeprecateDisable.message(cask)
-      output << "#{deprecate_disable.capitalize}\n" if deprecate_disable
+      if deprecate_disable.present?
+        deprecate_disable.tap { |message| message[0] = message[0].upcase }
+        output << "#{deprecate_disable}\n"
+      end
       output << "#{installation_info(cask)}\n"
       repo = repo_info(cask)
       output << "#{repo}\n" if repo

Library/Homebrew/deprecate_disable.rb

@@ -75,6 +75,20 @@ def message(formula_or_cask)
       end
     end
 
+    replacement = if formula_or_cask.deprecated?
+      formula_or_cask.deprecation_replacement
+    elsif formula_or_cask.disabled?
+      formula_or_cask.disable_replacement
+    end
+
+    if replacement.present?
+      message << "\n"
+      message << <<~EOS
+        Replacement:
+          brew install #{replacement}
+      EOS
+    end
+
     message
   end
 

Library/Homebrew/formula.rb

@@ -1542,6 +1542,13 @@
   # @see .deprecate!
   delegate deprecation_reason: :"self.class"
 
+  # The replacement for this deprecated {Formula}.
+  # Returns `nil` if no replacement is specified or the formula is not deprecated.
+  # @!method deprecation_replacement
+  # @return [String]
+  # @see .deprecate!
+  delegate deprecation_replacement: :"self.class"
+
   # Whether this {Formula} is disabled (i.e. cannot be installed).
   # Defaults to false.
   # @!method disabled?
@@ -1563,6 +1570,13 @@
   # @see .disable!
   delegate disable_reason: :"self.class"
 
+  # The replacement for this disabled {Formula}.
+  # Returns `nil` if no replacement is specified or the formula is not disabled.
+  # @!method disable_replacement
+  # @return [String]
+  # @see .disable!
+  delegate disable_replacement: :"self.class"
+
   sig { returns(T::Boolean) }
   def skip_cxxstdlib_check?
     false
@@ -2475,9 +2489,11 @@
       "deprecated"               => deprecated?,
       "deprecation_date"         => deprecation_date,
       "deprecation_reason"       => deprecation_reason,
+      "deprecation_replacement"  => deprecation_replacement,
       "disabled"                 => disabled?,
       "disable_date"             => disable_date,
       "disable_reason"           => disable_reason,
+      "disable_replacement"      => disable_replacement,
       "post_install_defined"     => post_install_defined?,
       "service"                  => (service.to_hash if service?),
       "tap_git_head"             => tap_git_head,
@@ -2568,11 +2584,13 @@
     if deprecation_date
       api_hash["deprecation_date"] = deprecation_date
       api_hash["deprecation_reason"] = deprecation_reason
+      api_hash["deprecation_replacement"] = deprecation_replacement
     end
 
     if disable_date
       api_hash["disable_date"] = disable_date
       api_hash["disable_reason"] = disable_reason
+      api_hash["disable_replacement"] = disable_replacement
     end
 
     api_hash
@@ -4268,14 +4286,19 @@
     # deprecate! date: "2020-08-27", because: "has been replaced by foo"
     # ```
     #
+    # ```ruby
+    # deprecate! date: "2020-08-27", because: "has been replaced by foo", replacement: "foo"
+    # ```
+    #
     # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae
     # @see DeprecateDisable::FORMULA_DEPRECATE_DISABLE_REASONS
     # @api public
-    def deprecate!(date:, because:)
+    def deprecate!(date:, because:, replacement: nil)
       @deprecation_date = Date.parse(date)
       return if @deprecation_date > Date.today
 
       @deprecation_reason = because
+      @deprecation_replacement = replacement
       @deprecated = true
     end
 
@@ -4301,6 +4324,13 @@
     # @see .deprecate!
     attr_reader :deprecation_reason
 
+    # The replacement for a deprecated {Formula}.
+    #
+    # @return [nil] if no replacement was provided or the formula is not deprecated.
+    # @return [String]
+    # @see .deprecate!
+    attr_reader :deprecation_replacement
+
     # Disables a {Formula} (on the given date) so it cannot be
     # installed. If the date has not yet passed the formula
     # will be deprecated instead of disabled.
@@ -4315,19 +4345,25 @@
     # disable! date: "2020-08-27", because: "has been replaced by foo"
     # ```
     #
+    # ```ruby
+    # disable! date: "2020-08-27", because: "has been replaced by foo", replacement: "foo"
+    # ```
+    #
     # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae
     # @see DeprecateDisable::FORMULA_DEPRECATE_DISABLE_REASONS
     # @api public
-    def disable!(date:, because:)
+    def disable!(date:, because:, replacement: nil)
       @disable_date = Date.parse(date)
 
       if @disable_date > Date.today
         @deprecation_reason = because
+        @deprecation_replacement = replacement
         @deprecated = true
         return
       end
 
       @disable_reason = because
+      @disable_replacement = replacement
       @disabled = true
     end
 
@@ -4354,6 +4390,13 @@
     # @see .disable!
     attr_reader :disable_reason
 
+    # The replacement for a disabled {Formula}.
+    # Returns `nil` if no reason was provided or the formula is not disabled.
+    #
+    # @return [String]
+    # @see .disable!
+    attr_reader :disable_replacement
+
     # Permit overwriting certain files while linking.
     #
     # ### Examples