From 7d26a61cc85580208da5d62e20278f512e8e0482 Mon Sep 17 00:00:00 2001
From: Mike McQuaid <mike@mikemcquaid.com>
Date: Sat, 30 Mar 2019 10:17:34 +0000
Subject: [PATCH] Deprecate tap pinning
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tap pinning is not used by Homebrew or the Homebrew maintainers so issues relating to pinned taps (#5418, #5796) don’t get fixed. Tap pinning does not work consistently or reliably and is conceptually confusing to encourage users to use fully-scoped user/tap/formula naming or avoid shadowing core tap formulae' names instead.
---
 Library/Homebrew/cmd/tap-pin.rb   | 4 ++++
 Library/Homebrew/cmd/tap-unpin.rb | 4 ++++
 Library/Homebrew/formulary.rb     | 4 ++++
 docs/Manpage.md                   | 9 ---------
 manpages/brew.1                   | 6 ------
 5 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/Library/Homebrew/cmd/tap-pin.rb b/Library/Homebrew/cmd/tap-pin.rb
index 0617e5ea8e..c04bae48fc 100644
--- a/Library/Homebrew/cmd/tap-pin.rb
+++ b/Library/Homebrew/cmd/tap-pin.rb
@@ -12,10 +12,14 @@ module Homebrew
         by the user. See also `tap-unpin`.
       EOS
       switch :debug
+      hide_from_man_page!
     end
   end
 
   def tap_pin
+    odeprecated "brew tap-pin user/tap",
+      "fully-scoped user/tap/formula naming"
+
     tap_pin_args.parse
 
     ARGV.named.each do |name|
diff --git a/Library/Homebrew/cmd/tap-unpin.rb b/Library/Homebrew/cmd/tap-unpin.rb
index 7d030b969b..25fc23bf59 100644
--- a/Library/Homebrew/cmd/tap-unpin.rb
+++ b/Library/Homebrew/cmd/tap-unpin.rb
@@ -11,10 +11,14 @@ module Homebrew
         Unpin <tap> so its formulae are no longer prioritised. See also `tap-pin`.
       EOS
       switch :debug
+      hide_from_man_page!
     end
   end
 
   def tap_unpin
+    odeprecated "brew tap-pin user/tap",
+      "fully-scoped user/tap/formula naming"
+
     tap_unpin_args.parse
 
     ARGV.named.each do |name|
diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb
index 8b40c7376f..9722eeafdc 100644
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@@ -460,9 +460,13 @@ module Formulary
     if possible_pinned_tap_formulae.size == 1
       selected_formula = factory(possible_pinned_tap_formulae.first, spec)
       if core_path(ref).file?
+        odeprecated "brew tap-pin user/tap",
+          "fully-scoped user/tap/formula naming"
         opoo <<~EOS
           #{ref} is provided by core, but is now shadowed by #{selected_formula.full_name}.
+          This behaviour is deprecated and will be removed in Homebrew 2.2.0.
           To refer to the core formula, use Homebrew/core/#{ref} instead.
+          To refer to the tap formula, use #{selected_formula.full_name} instead.
         EOS
       end
       selected_formula
diff --git a/docs/Manpage.md b/docs/Manpage.md
index a47c0784ef..317536e7e1 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -488,15 +488,6 @@ summary of all installed taps if no *`tap`* are passed.
 * `--json`:
   Print a JSON representation of *`taps`*. Currently the default and only accepted value for *`version`* is `v1`. See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew>
 
-### `tap-pin` *`tap`*
-
-Pin *`tap`*, prioritising its formulae over core when formula names are supplied
-by the user. See also `tap-unpin`.
-
-### `tap-unpin` *`tap`*
-
-Unpin *`tap`* so its formulae are no longer prioritised. See also `tap-pin`.
-
 ### `uninstall`, `rm`, `remove` [*`options`*] *`formula`*
 
 Uninstall *`formula`*.
diff --git a/manpages/brew.1 b/manpages/brew.1
index 0816a4624f..c9c4f9649e 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -612,12 +612,6 @@ Display information on all installed taps\.
 \fB\-\-json\fR
 Print a JSON representation of \fItaps\fR\. Currently the default and only accepted value for \fIversion\fR is \fBv1\fR\. See the docs for examples of using the JSON output: \fIhttps://docs\.brew\.sh/Querying\-Brew\fR
 .
-.SS "\fBtap\-pin\fR \fItap\fR"
-Pin \fItap\fR, prioritising its formulae over core when formula names are supplied by the user\. See also \fBtap\-unpin\fR\.
-.
-.SS "\fBtap\-unpin\fR \fItap\fR"
-Unpin \fItap\fR so its formulae are no longer prioritised\. See also \fBtap\-pin\fR\.
-.
 .SS "\fBuninstall\fR, \fBrm\fR, \fBremove\fR [\fIoptions\fR] \fIformula\fR"
 Uninstall \fIformula\fR\.
 .