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

@@ -126,6 +126,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 +194,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)}:"
+    unless pinned.empty?
+      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(", "))

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`*.

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\.
 .