From bb3620301a59fa540c362ba2ce9dbff6dabba6a1 Mon Sep 17 00:00:00 2001
From: apainintheneck <apainintheneck@gmail.com>
Date: Tue, 5 Dec 2023 23:11:59 -0800
Subject: [PATCH] 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     | 3 +++
 Library/Homebrew/cmd/upgrade.rb | 7 +++++--
 Library/Homebrew/upgrade.rb     | 2 +-
 docs/Manpage.md                 | 3 +++
 manpages/brew.1                 | 3 +++
 5 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/Library/Homebrew/cmd/pin.rb b/Library/Homebrew/cmd/pin.rb
index cd5d91edbfb46e..8e1413e9545dd2 100644
--- a/Library/Homebrew/cmd/pin.rb
+++ b/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
diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb
index a50bd8a1c9a6e8..89d043b9767947 100644
--- a/Library/Homebrew/cmd/upgrade.rb
+++ b/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
 
diff --git a/Library/Homebrew/upgrade.rb b/Library/Homebrew/upgrade.rb
index 2541bd376d7130..3fa1929ce3c8e7 100644
--- a/Library/Homebrew/upgrade.rb
+++ b/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(", "))
diff --git a/docs/Manpage.md b/docs/Manpage.md
index ff7bcdefc061f3..e38c0899ea9efb 100644
--- a/docs/Manpage.md
+++ b/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`*.
diff --git a/manpages/brew.1 b/manpages/brew.1
index fc6d51345b76c8..0d65d1f1ecdf63 100644
--- a/manpages/brew.1
+++ b/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\.
 .