cmd/pin: Update pinned formula messaging

The hope is that this will be clearer and less annoying for users.

A user came to us a couple weeks ago stating that it was confusing
that the `brew upgrade` command printed an error when a pinned
formula had a new version available and didn't get upgraded.

This PR changes that message to a warning from an error. While looking
into this we found that there is another message that gets printed
when a package dependency doesn't get upgraded because it is pinned
and that got turned into a warning from a normal message. Honestly,
that should be more worrying for the user anyway; it could lead to
a program not working correctly in the worst case.

I also added a message to the `brew pin` command warning about
potential unintended behavior if a dependency gets pinned and another
package requires a newer version of it.

Lastly, I added a commented out deprecation notice for the
`brew upgrade --ignore-pinned` command since it's now the default.

Library/Homebrew/cmd/pin.rb

@@ -13,6 +13,9 @@ def pin_args
       description <<~EOS
         Pin the specified <formula>, preventing them from being upgraded when
         issuing the `brew upgrade` <formula> command. See also `unpin`.
+
+        Note: Other packages which depend on newer versions of a pinned formula
+        might not install or run correctly.
       EOS
 
       named_args :installed_formula, min: 1

Library/Homebrew/cmd/upgrade.rb

@@ -62,6 +62,7 @@ def upgrade_args
         }],
         [:switch, "--ignore-pinned", {
           description: "Set a successful exit status even if pinned formulae are not upgraded.",
+          hidden:      true,
         }],
         [:switch, "--keep-tmp", {
           description: "Retain the temporary files created during installation.",
@@ -126,6 +127,9 @@ def upgrade_args
   def upgrade
     args = upgrade_args.parse
 
+    # Deprecated since this is now the default behavior.
+    # odeprecated "`brew upgrade --ignore-pinned`" if args.ignore_pinned?
+
     formulae, casks = args.named.to_resolved_formulae_to_casks
     # If one or more formulae are specified, but no casks were
     # specified, we want to make note of that so we don't
@@ -191,8 +195,8 @@ def upgrade_outdated_formulae(formulae, args:)
       end
     end
 
-    if !pinned.empty? && !args.ignore_pinned?
-      ofail "Not upgrading #{pinned.count} pinned #{Utils.pluralize("package", pinned.count)}:"
+    if pinned.any?
+      opoo "Not upgrading #{pinned.count} pinned #{Utils.pluralize("package", pinned.count)}:"
       puts pinned.map { |f| "#{f.full_specified_name} #{f.pkg_version}" } * ", "
     end
 

Library/Homebrew/upgrade.rb

@@ -337,7 +337,7 @@ def check_installed_dependents(
 
       if pinned_dependents.present?
         plural = Utils.pluralize("dependent", pinned_dependents.count)
-        ohai "Not upgrading #{pinned_dependents.count} pinned #{plural}:"
+        opoo "Not upgrading #{pinned_dependents.count} pinned #{plural}:"
         puts(pinned_dependents.map do |f|
           "#{f.full_specified_name} #{f.pkg_version}"
         end.join(", "))

completions/bash/brew

@@ -2565,7 +2565,6 @@ _brew_upgrade() {
       --greedy-auto-updates
       --greedy-latest
       --help
-      --ignore-pinned
       --input-methoddir
       --interactive
       --internet-plugindir

completions/fish/brew.fish

@@ -1672,7 +1672,6 @@ __fish_brew_complete_arg 'upgrade' -l greedy -d 'Also include casks with `auto_u
 __fish_brew_complete_arg 'upgrade' -l greedy-auto-updates -d 'Also include casks with `auto_updates true`'
 __fish_brew_complete_arg 'upgrade' -l greedy-latest -d 'Also include casks with `version :latest`'
 __fish_brew_complete_arg 'upgrade' -l help -d 'Show this message'
-__fish_brew_complete_arg 'upgrade' -l ignore-pinned -d 'Set a successful exit status even if pinned formulae are not upgraded'
 __fish_brew_complete_arg 'upgrade' -l input-methoddir -d 'Target location for Input Methods (default: `~/Library/Input Methods`)'
 __fish_brew_complete_arg 'upgrade' -l interactive -d 'Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package'
 __fish_brew_complete_arg 'upgrade' -l internet-plugindir -d 'Target location for Internet Plugins (default: `~/Library/Internet Plug-Ins`)'

completions/zsh/_brew

@@ -2060,7 +2060,6 @@ _brew_upgrade() {
     '(--formula)--greedy-auto-updates[Also include casks with `auto_updates true`]' \
     '(--formula)--greedy-latest[Also include casks with `version :latest`]' \
     '--help[Show this message]' \
-    '(--cask)--ignore-pinned[Set a successful exit status even if pinned formulae are not upgraded]' \
     '(--formula)--input-methoddir[Target location for Input Methods (default: `~/Library/Input Methods`)]' \
     '(--cask)--interactive[Download and patch formula, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package]' \
     '(--formula)--internet-plugindir[Target location for Internet Plugins (default: `~/Library/Internet Plug-Ins`)]' \

docs/Manpage.md

@@ -541,6 +541,9 @@ information is displayed in interactive shells, and suppressed otherwise.
 Pin the specified *`formula`*, preventing them from being upgraded when
 issuing the `brew upgrade` *`formula`* command. See also `unpin`.
 
+Note: Other packages which depend on newer versions of a pinned formula
+might not install or run correctly.
+
 ### `postinstall`, `post_install` *`installed_formula`* [...]
 
 Rerun the post-install steps for *`formula`*.
@@ -797,8 +800,6 @@ upgraded formulae or, every 30 days, for all formulae.
   Install from a bottle if it exists for the current or newest version of macOS, even if it would not normally be used for installation.
 * `--fetch-HEAD`:
   Fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the repository's HEAD will only be checked for updates when a new stable or development version has been released.
-* `--ignore-pinned`:
-  Set a successful exit status even if pinned formulae are not upgraded.
 * `--keep-tmp`:
   Retain the temporary files created during installation.
 * `--debug-symbols`:

manpages/brew.1

@@ -758,6 +758,9 @@ Also include outdated casks including those with \fBauto_updates true\fR\.
 .SS "\fBpin\fR \fIinstalled_formula\fR [\.\.\.]"
 Pin the specified \fIformula\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR \fIformula\fR command\. See also \fBunpin\fR\.
 .
+.P
+Note: Other packages which depend on newer versions of a pinned formula might not install or run correctly\.
+.
 .SS "\fBpostinstall\fR, \fBpost_install\fR \fIinstalled_formula\fR [\.\.\.]"
 Rerun the post\-install steps for \fIformula\fR\.
 .
@@ -1103,10 +1106,6 @@ Install from a bottle if it exists for the current or newest version of macOS, e
 Fetch the upstream repository to detect if the HEAD installation of the formula is outdated\. Otherwise, the repository\'s HEAD will only be checked for updates when a new stable or development version has been released\.
 .
 .TP
-\fB\-\-ignore\-pinned\fR
-Set a successful exit status even if pinned formulae are not upgraded\.
-.
-.TP
 \fB\-\-keep\-tmp\fR
 Retain the temporary files created during installation\.
 .