brew.rb: tell more people to not report issues.

- We should tell people to not report issues if they are running in an
  unsupported configuration.
- We should tell people to run `brew update` before reporting issues if
  they have `HOMEBREW_NO_AUTO_UPDATE` set.
- We should tell people to not report issues in more types of
  exceptions.
- Warn people in `HOMEBREW_NO_AUTO_UPDATE` documentation.
- DRY up `brew.rb` exception handling.

Co-authored-by: Colin Dean <colindean@users.noreply.github.com>

Library/Homebrew/brew.rb

@@ -148,7 +148,9 @@ rescue BuildError => e
   Utils::Analytics.report_build_error(e)
   e.dump(verbose: args&.verbose?)
 
-  if e.formula.head? || e.formula.deprecated? || e.formula.disabled?
+  if OS.unsupported_configuration?
+    $stderr.puts "#{Tty.bold}Do not report this issue: you are running in an unsupported configuration.#{Tty.reset}"
+  elsif e.formula.head? || e.formula.deprecated? || e.formula.disabled?
     reason = if e.formula.head?
       "was built from an unstable upstream --HEAD"
     elsif e.formula.deprecated?
@@ -166,35 +168,35 @@ rescue BuildError => e
       Try to figure out the problem yourself and submit a fix as a pull request.
       We will review it but may or may not accept it.
     EOS
+
   end
 
-  exit 1
-rescue RuntimeError, SystemCallError => e
-  raise if e.message.empty?
-
-  onoe e
-  $stderr.puts Utils::Backtrace.clean(e) if args&.debug? || ARGV.include?("--debug")
-
-  exit 1
-rescue MethodDeprecatedError => e
-  onoe e
-  if e.issues_url
-    $stderr.puts "If reporting this issue please do so at (not Homebrew/brew or Homebrew/homebrew-core):"
-    $stderr.puts "  #{Formatter.url(e.issues_url)}"
-  end
-  $stderr.puts Utils::Backtrace.clean(e) if args&.debug? || ARGV.include?("--debug")
   exit 1
 rescue Exception => e # rubocop:disable Lint/RescueException
+  runtime_or_system_call_error = e.is_a?(RuntimeError) || e.is_a?(SystemCallError)
+  raise if runtime_or_system_call_error && e.message.empty?
+
   onoe e
-  if internal_cmd && !OS.unsupported_configuration?
-    if Homebrew::EnvConfig.no_auto_update?
-      $stderr.puts "#{Tty.bold}Do not report this issue until you've run `brew update` and tried again.#{Tty.reset}"
-    else
-      $stderr.puts "#{Tty.bold}Please report this issue:#{Tty.reset}"
-      $stderr.puts "  #{Formatter.url(OS::ISSUES_URL)}"
-    end
+
+  method_deprecated_error = e.is_a?(MethodDeprecatedError)
+  runtime_or_system_call_or_method_deprecated_error = runtime_or_system_call_error || method_deprecated_error
+  if args&.debug? || ARGV.include?("--debug") || !runtime_or_system_call_or_method_deprecated_error
+    $stderr.puts Utils::Backtrace.clean(e)
   end
-  $stderr.puts Utils::Backtrace.clean(e)
+
+  if OS.unsupported_configuration?
+    $stderr.puts "#{Tty.bold}Do not report this issue: you are running in an unsupported configuration.#{Tty.reset}"
+  elsif Homebrew::EnvConfig.no_auto_update?
+    $stderr.puts "#{Tty.bold}You have disabled automatic updates.#{Tty.reset}"
+    $stderr.puts "#{Tty.bold}Do not report this issue until you've run `brew update` and tried again.#{Tty.reset}"
+  elsif (issues_url = (method_deprecated_error && e.issues_url) || Utils::Backtrace.tap_error_url(e))
+    $stderr.puts "If reporting this issue please do so at (not Homebrew/brew or Homebrew/homebrew-core):"
+    $stderr.puts "  #{Formatter.url(issues_url)}"
+  elsif internal_cmd
+    $stderr.puts "#{Tty.bold}Please report this issue:#{Tty.reset}"
+    $stderr.puts "  #{Formatter.url(OS::ISSUES_URL)}"
+  end
+
   exit 1
 else
   exit 1 if Homebrew.failed?

Library/Homebrew/env_config.rb

@@ -268,8 +268,10 @@ module Homebrew
       },
       HOMEBREW_NO_AUTO_UPDATE:                   {
         description: "If set, do not automatically update before running some commands, e.g. " \
-                     "`brew install`, `brew upgrade` and `brew tap`. Alternatively, " \
-                     "run this less often by setting `HOMEBREW_AUTO_UPDATE_SECS` to a value higher than the default.",
+                     "`brew install`, `brew upgrade` and `brew tap`. Preferably, " \
+                     "run this less often by setting `HOMEBREW_AUTO_UPDATE_SECS` to a value higher than the " \
+                     "default. Note that setting this and e.g. tapping new taps may result in a broken  " \
+                     "configuration. Please ensure you always run `brew update` before reporting any issues.",
         boolean:     true,
       },
       HOMEBREW_NO_BOOTSNAP:                      {

Library/Homebrew/utils/backtrace.rb

@@ -20,10 +20,12 @@ module Utils
                .tap { |new_backtrace| print_backtrace_message if old_backtrace_length > new_backtrace.length }
     end
 
+    sig { returns(String) }
     def self.sorbet_runtime_path
       @sorbet_runtime_path ||= "#{Gem.paths.home}/gems/sorbet-runtime"
     end
 
+    sig { void }
     def self.print_backtrace_message
       return if @print_backtrace_message
 
@@ -32,5 +34,19 @@ module Utils
 
       @print_backtrace_message = true
     end
+
+    sig { params(error: Exception).returns(T.nilable(String)) }
+    def self.tap_error_url(error)
+      backtrace = error.backtrace
+      return if backtrace.blank?
+
+      backtrace.each do |line|
+        if (tap = line.match(%r{/Library/Taps/([^/]+/[^/]+)/}))
+          return "https://github.com/#{tap[1]}/issues/new"
+        end
+      end
+
+      nil
+    end
   end
 end

docs/Manpage.md

@@ -3740,8 +3740,11 @@ command execution e.g. `$(cat file)`.
 `HOMEBREW_NO_AUTO_UPDATE`
 
 : If set, do not automatically update before running some commands, e.g. `brew
-  install`, `brew upgrade` and `brew tap`. Alternatively, run this less often by
-  setting `HOMEBREW_AUTO_UPDATE_SECS` to a value higher than the default.
+  install`, `brew upgrade` and `brew tap`. Preferably, run this less often by
+  setting `HOMEBREW_AUTO_UPDATE_SECS` to a value higher than the default. Note
+  that setting this and e.g. tapping new taps may result in a broken
+  configuration. Please ensure you always run `brew update` before reporting any
+  issues.
 
 `HOMEBREW_NO_BOOTSNAP`
 

manpages/brew.1

@@ -1,5 +1,5 @@
 .\" generated by kramdown
-.TH "BREW" "1" "March 2024" "Homebrew"
+.TH "BREW" "1" "April 2024" "Homebrew"
 .SH NAME
 brew \- The Missing Package Manager for macOS (or Linux)
 .SH "SYNOPSIS"
@@ -2445,7 +2445,7 @@ If set, do not send analytics\. Google Analytics were destroyed\. For more infor
 .UE
 .TP
 \fBHOMEBREW_NO_AUTO_UPDATE\fP
-If set, do not automatically update before running some commands, e\.g\. \fBbrew install\fP, \fBbrew upgrade\fP and \fBbrew tap\fP\&\. Alternatively, run this less often by setting \fBHOMEBREW_AUTO_UPDATE_SECS\fP to a value higher than the default\.
+If set, do not automatically update before running some commands, e\.g\. \fBbrew install\fP, \fBbrew upgrade\fP and \fBbrew tap\fP\&\. Preferably, run this less often by setting \fBHOMEBREW_AUTO_UPDATE_SECS\fP to a value higher than the default\. Note that setting this and e\.g\. tapping new taps may result in a broken configuration\. Please ensure you always run \fBbrew update\fP before reporting any issues\.
 .TP
 \fBHOMEBREW_NO_BOOTSNAP\fP
 If set, do not use Bootsnap to speed up repeated \fBbrew\fP calls\.