From 9dec442e715a351791bc9ce18cae57d96cb718b5 Mon Sep 17 00:00:00 2001
From: EricFromCanada <enk3@outlook.com>
Date: Fri, 4 Dec 2020 11:39:02 -0500
Subject: [PATCH] pr-pull: prepare replacement for --workflow flag

---
 Library/Homebrew/cli/parser.rb      | 9 +++++++--
 Library/Homebrew/dev-cmd/pr-pull.rb | 4 +++-
 docs/Manpage.md                     | 2 +-
 manpages/brew.1                     | 2 +-
 4 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/Library/Homebrew/cli/parser.rb b/Library/Homebrew/cli/parser.rb
index 35f7fd7124030..d1e731dbf1610 100644
--- a/Library/Homebrew/cli/parser.rb
+++ b/Library/Homebrew/cli/parser.rb
@@ -194,7 +194,7 @@ def comma_array(name, description: nil)
         end
       end
 
-      def flag(*names, description: nil, required_for: nil, depends_on: nil)
+      def flag(*names, description: nil, replacement: nil, required_for: nil, depends_on: nil)
         required = if names.any? { |name| name.end_with? "=" }
           OptionParser::REQUIRED_ARGUMENT
         else
@@ -202,8 +202,13 @@ def flag(*names, description: nil, required_for: nil, depends_on: nil)
         end
         names.map! { |name| name.chomp "=" }
         description = option_to_description(*names) if description.nil?
-        process_option(*names, description)
+        if replacement.nil?
+          process_option(*names, description)
+        else
+          description += " (disabled#{"; replaced by #{replacement}" if replacement.present?})"
+        end
         @parser.on(*names, *wrap_option_desc(description), required) do |option_value|
+          odisabled "the `#{names.first}` flag", replacement unless replacement.nil?
           names.each do |name|
             @args[option_to_name(name)] = option_value
           end
diff --git a/Library/Homebrew/dev-cmd/pr-pull.rb b/Library/Homebrew/dev-cmd/pr-pull.rb
index daa2bcaf2faa4..de6f2abef6da8 100644
--- a/Library/Homebrew/dev-cmd/pr-pull.rb
+++ b/Library/Homebrew/dev-cmd/pr-pull.rb
@@ -51,7 +51,9 @@ def pr_pull_args
              description: "Message to include when autosquashing revision bumps, deletions, and rebuilds."
       flag   "--workflow=",
              description: "Retrieve artifacts from the specified workflow (default: `tests.yml`). "\
-                          "Legacy: use --workflows instead"
+                          "*Legacy:* use `--workflows` instead."
+      # TODO: enable for next major/minor release
+      #      replacement: "`--workflows`"
       flag   "--artifact=",
              description: "Download artifacts with the specified name (default: `bottles`)."
       flag   "--bintray-org=",
diff --git a/docs/Manpage.md b/docs/Manpage.md
index 34fe4fcf8a461..a32a0e301d1ad 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -1141,7 +1141,7 @@ Requires write access to the repository.
 * `--message`:
   Message to include when autosquashing revision bumps, deletions, and rebuilds.
 * `--workflow`:
-  Retrieve artifacts from the specified workflow (default: `tests.yml`). Legacy: use --workflows instead
+  Retrieve artifacts from the specified workflow (default: `tests.yml`). *Legacy:* use `--workflows` instead.
 * `--artifact`:
   Download artifacts with the specified name (default: `bottles`).
 * `--bintray-org`:
diff --git a/manpages/brew.1 b/manpages/brew.1
index 57fe82d383b44..1f259691586e9 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -1589,7 +1589,7 @@ Message to include when autosquashing revision bumps, deletions, and rebuilds\.
 .
 .TP
 \fB\-\-workflow\fR
-Retrieve artifacts from the specified workflow (default: \fBtests\.yml\fR)\. Legacy: use \-\-workflows instead
+Retrieve artifacts from the specified workflow (default: \fBtests\.yml\fR)\. \fILegacy:\fR use \fB\-\-workflows\fR instead\.
 .
 .TP
 \fB\-\-artifact\fR