upgrade: announce usage of --all.

Tell users that we will soon be migrating `--all` so it is required if
you wish to upgrade all formulae.

Closes Homebrew/homebrew#38572.

Library/Homebrew/cmd/upgrade.rb

@@ -5,10 +5,17 @@ module Homebrew
   def upgrade
     Homebrew.perform_preinstall_checks
 
-    if ARGV.named.empty?
+    if ARGV.include?("--all") || ARGV.named.empty?
+      unless ARGV.include? "--all"
+        opoo <<-EOS.undent
+          brew upgrade with no arguments will change behaviour soon!
+          It currently upgrades all formula but this will soon change to require '--all'.
+          Please update any workflows, documentation and scripts!
+        EOS
+      end
       outdated = Homebrew.outdated_brews(Formula.installed)
       exit 0 if outdated.empty?
-    else
+    elsif ARGV.named.any?
       outdated = Homebrew.outdated_brews(ARGV.formulae)
 
       (ARGV.formulae - outdated).each do |f|
@@ -20,6 +27,11 @@ module Homebrew
         end
       end
       exit 1 if outdated.empty?
+    else
+      # This will currently never be reached but is implemented to make the
+      # migration to --all easier in the future (as just the ARGV.named.empty?
+      # will need removed above).
+      odie "Either --all or one or more formulae must be specified!"
     end
 
     unless upgrade_pinned?

Library/Homebrew/manpages/brew.1.md

@@ -390,11 +390,15 @@ Note that these flags should only appear after a command.
 
     If `--rebase` is specified then `git pull --rebase` is used.
 
-  * `upgrade [install-options]` [<formulae>]:
+  * `upgrade [--all] [install-options]` [<formulae>]:
     Upgrade outdated, unpinned brews.
 
     Options for the `install` command are also valid here.
 
+    If `--all` is passed, upgrade all formulae. This is currently the same
+    behaviour as without `--all` but soon `--all` will be required to upgrade
+    all formulae.
+
     If <formulae> are given, upgrade only the specified brews (but do so even
     if they are pinned; see `pin`, `unpin`).
 

share/man/man1/brew.1

@@ -415,13 +415,16 @@ Fetch the newest version of Homebrew and all formulae from GitHub using \fBgit\f
 If \fB\-\-rebase\fR is specified then \fBgit pull \-\-rebase\fR is used\.
 .
 .TP
-\fBupgrade [install\-options]\fR [\fIformulae\fR]
+\fBupgrade [\-\-all] [install\-options]\fR [\fIformulae\fR]
 Upgrade outdated, unpinned brews\.
 .
 .IP
 Options for the \fBinstall\fR command are also valid here\.
 .
 .IP
+If \fB\-\-all\fR is passed, upgrade all formulae\. This is currently the same behaviour as without \fB\-\-all\fR but soon \fB\-\-all\fR will be required to upgrade all formulae\.
+.
+.IP
 If \fIformulae\fR are given, upgrade only the specified brews (but do so even if they are pinned; see \fBpin\fR, \fBunpin\fR)\.
 .
 .TP