Document ERC 5.5 regressions in new 29.1-specific version

From 0d1eec378a57295bc0ce6af2cb6a54ee9b379705 Mon Sep 17 00:00:00 2001
From: "F. Jason Park" <[email protected]>
Date: Fri, 21 Apr 2023 07:39:05 -0700
Subject: [PATCH 1/2] * doc/misc/erc.texi: Elaborate on upgrading via ELPA.

---
 doc/misc/erc.texi | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index b80affbc954..ad30546c9d5 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -1477,10 +1477,30 @@ Getting Help and Reporting Bugs
 same network, for more involved questions.
 
 @item
+@anchor{Upgrading}
 You can check GNU ELPA between Emacs releases to see if a newer
 version is available that might contain a fix for your issue:
 @uref{https://elpa.gnu.org/packages/erc.html}.
 
+To upgrade, run @kbd{M-x list-packages @key{RET}}.  In the
+@file{*Packages*} (@code{package-menu-mode}) buffer, click the
+@samp{erc} package link for the desired version.  If unsure, or if the
+version column is too narrow to tell, try the bottom-most candidate.
+In the resulting @code{help-mode} buffer, confirm the version and
+click @samp{Install}.  Make sure to restart Emacs before reconnecting
+to IRC, and don't forget that you can roll back to the previous
+version by running @kbd{M-x package-delete @key{RET}}.
+@xref{Packages,,,emacs, the Emacs manual} for more information.
+
+In the rare instance you need an emergency fix or have volunteered to
+test an edge feature between ERC releases, you can try adding
+@samp{("devel" . "https://elpa.gnu.org/devel/")} to
+@code{package-archives} prior to performing the steps above.  For
+this, you'll want to instead select a ``snapshot'' version from the
+menu.  Please be aware that when going this route, the latest changes
+may not yet be available and you run the risk of incurring other bugs
+and encountering unstable features.
+
 @item
 To report a bug in ERC, use @kbd{M-x erc-bug}.
 
-- 
2.39.2

From c154bcde8ceb10b038a92a997bfb929123f11cde Mon Sep 17 00:00:00 2001
From: "F. Jason Park" <[email protected]>
Date: Fri, 21 Apr 2023 07:39:05 -0700
Subject: [PATCH 2/2] Explain ERC 5.5 regressions in new version 5.5.0.29.1

* doc/misc/erc.texi: Bump version to 5.5.0.29.1.
* etc/ERC-NEWS: Don't hype bugged option `erc-reconnect-display'.
* lisp/erc/erc-dcc.el (erc-dcc-do-GET-command): Add comment explaining
parsing bug in ERC 5.5 (bug#62444).
* lisp/erc/erc-networks.el (erc-networks-on-MOTD-end): Mention known
/MOTD bug in error notice so people don't waste energy reporting
it (bug#62151).
* lisp/erc/erc.el: Change Version header to 5.5.0.29.1.  Don't bother
updating the `customize-package-emacs-version-alist' entry
because no option defaults are affected.
(erc-version): Change version to 5.5.0.29.1.
(erc-reconnect-display, erc-query-on-unjoined-chan-privmsg): Add
warning to doc strings and `custom-set' functions.  It's believed that
these bugs degrade the user experience significantly enough to warrant
such mentions (bug#62833).
(erc-query): Fix erroneous redirect string in deprecation spec.
Do not merge to master.
---
 doc/misc/erc.texi        |  2 +-
 etc/ERC-NEWS             |  4 +---
 lisp/erc/erc-dcc.el      |  6 +++++-
 lisp/erc/erc-networks.el | 10 +++++++--
 lisp/erc/erc.el          | 44 ++++++++++++++++++++++++++++++++--------
 5 files changed, 50 insertions(+), 16 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index ad30546c9d5..7f26b9ed181 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -2,7 +2,7 @@
 @c %**start of header
 @setfilename ../../info/erc.info
 @settitle ERC Manual
-@set ERCVER 5.5
+@set ERCVER 5.5.0.29.1
 @set ERCDIST as distributed with Emacs @value{EMACSVER}
 @include docstyle.texi
 @syncodeindex fn cp
diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS
index 434bfab94e9..9672a86345b 100644
--- a/etc/ERC-NEWS
+++ b/etc/ERC-NEWS
@@ -80,9 +80,7 @@ can now opt for an improved 'window-noselect' instead.  It still
 offers the same pronounced visual cue when connecting and joining but
 now avoids any hijacking of the active window as well.
 
-Beyond this, additional flexibility is now available for controlling
-the behavior of newly created target buffers during reconnection.
-See the option 'erc-reconnect-display' for more.
+(Edited for ERC 5.5.0.29.1 in Emacs 29.1.)
 
 ** Improved handling of multiline prompt input.
 This means better detection and handling of intervening and trailing
diff --git a/lisp/erc/erc-dcc.el b/lisp/erc/erc-dcc.el
index 4c557e0e0f9..8fc30fddb46 100644
--- a/lisp/erc/erc-dcc.el
+++ b/lisp/erc/erc-dcc.el
@@ -508,7 +508,11 @@ erc-dcc-do-GET-command
   "Do a DCC GET command.  NICK is the person who is sending the file.
 FILE is the filename.  If FILE is split into multiple arguments,
 re-join the arguments, separated by a space.
-PROC is the server process."
+PROC is the server process.
+
+WARNING: the /DCC GET command is bugged in ERC 5.5 (Emacs 29).
+File names containing the string \" -\" are not honored.  If you
+need a fix immediately, see Info node `(erc) Upgrading'."
   (let* ((args (seq-group-by (lambda (s) (eq ?- (aref s 0))) (cons nick file)))
          (flags (prog1 (cdr (assq t args))
                   (setq args (cdr (assq nil args))
diff --git a/lisp/erc/erc-networks.el b/lisp/erc/erc-networks.el
index 95fd8990c99..97ab8ecced3 100644
--- a/lisp/erc/erc-networks.el
+++ b/lisp/erc/erc-networks.el
@@ -1494,8 +1494,14 @@ erc-networks-on-MOTD-end
                                       (memq (erc--target-symbol erc--target)
                                             erc-networks--bouncer-targets)))
                                proc)
-      (let ((m (concat "Unexpected state detected. Please report via "
-                       (substitute-command-keys "\\[erc-bug]") ".")))
+      (require 'info nil t)
+      (let ((m (concat "Unexpected state detected. If you've just issued an"
+                       " /MOTD, please know that the command is bugged in ERC"
+                       " 5.5 (Emacs 29) but will be fixed in the next release."
+                       " Otherwise, please report this occurrence via"
+                       (substitute-command-keys " \\[erc-bug].")
+                       " For additional help options, see"
+                       " Info:\"(erc) Getting Help and Reporting Bugs\".")))
         (erc-display-error-notice parsed m))))
 
   ;; For now, retain compatibility with erc-server-NNN-functions.
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 69bdb5d71b1..42b4bec9e1c 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -12,7 +12,7 @@
 ;;               David Edmondson ([email protected])
 ;;               Michael Olson ([email protected])
 ;;               Kelvin White ([email protected])
-;; Version: 5.5
+;; Version: 5.5.0.29.1
 ;; Package-Requires: ((emacs "27.1") (compat "29.1.3.4"))
 ;; Keywords: IRC, chat, client, Internet
 ;; URL: https://www.gnu.org/software/emacs/erc.html
@@ -71,7 +71,7 @@
 (require 'iso8601)
 (eval-when-compile (require 'subr-x) (require 'url-parse))
 
-(defconst erc-version "5.5"
+(defconst erc-version "5.5.0.29.1"
   "This version of ERC.")
 
 (defvar erc-official-location
@@ -1495,9 +1495,20 @@ erc-reconnect-display
 This only affects automatic reconnections and is ignored when
 issuing a /reconnect command or reinvoking `erc-tls' with the
 same args (assuming success, of course).  See `erc-join-buffer'
-for a description of possible values."
+for a description of possible values.
+
+WARNING: this option is bugged in ERC 5.5 (Emacs 29).  Setting it
+to anything other than nil results in the chosen value being
+permanently adopted by all other buffer-display options for the
+remainder of the ERC session.  If you need this fixed
+immediately, see Info node `(erc) Upgrading'."
   :package-version '(ERC . "5.5")
   :group 'erc-buffers
+  :set (lambda (sym val)
+         (when val
+           (lwarn 'erc :warning "Setting `%s' to `%s' is currently bugged; %s"
+                  sym val "see doc string for more information."))
+         (set sym val))
   :type '(choice (const :tag "Use value of `erc-join-buffer'" nil)
                  (const :tag "Split window and select" window)
                  (const :tag "Split window, don't select" window-noselect)
@@ -4501,7 +4512,7 @@ erc-query
   "Open a query buffer on TARGET using SERVER-BUFFER.
 To change how this query window is displayed, use `let' to bind
 `erc-join-buffer' before calling this."
-  (declare (obsolete "bind `erc-cmd-query' and call `erc-cmd-QUERY'" "29.1"))
+  (declare (obsolete "call `erc-open' in a live server buffer" "29.1"))
   (unless (buffer-live-p server-buffer)
     (error "Couldn't switch to server buffer"))
   (with-current-buffer server-buffer
@@ -4524,16 +4535,31 @@ erc-auto-query
                  (const :tag "Use current buffer" buffer)
                  (const :tag "Use current buffer" t)))
 
-;; FIXME either retire this or put it to use after determining how
-;; it's meant to work.  Clearly, the doc string does not describe
-;; current behavior.  It's currently only used by the obsolete
-;; function `erc-auto-query'.
 (defcustom erc-query-on-unjoined-chan-privmsg t
   "If non-nil create query buffer on receiving any PRIVMSG at all.
 This includes PRIVMSGs directed to channels.  If you are using an IRC
 bouncer, such as dircproxy, to keep a log of channels when you are
-disconnected, you should set this option to t."
+disconnected, you should set this option to t.
+
+WARNING: this option was mistakenly removed from ERC 5.5's client
+code, so setting it to nil is temporarily ineffective.  That is,
+ERC now always creates a buffer when receiving a PRIVMSG directed
+at a channel for which none exists.  Note also that despite the
+option's name and the upper portion of this doc string, in which
+\"query\" appears to refer to any exchange with a target other
+than the server itself, the option did not previously allow for
+opting out of buffer creation for direct messages, at least not
+in Emacs 27 and 28.  However, such behavior continues to be
+attainable by setting `erc-auto-query' to nil.  If needing to
+restore pre-5.5 functionality immediately, see Info node `(erc)
+Upgrading'."
   :group 'erc-query
+  :set (lambda (sym val)
+         (unless val
+           (lwarn 'erc :warning
+                  "Setting `%s' to nil is currently ineffective; %s"
+                  sym "see doc string for details."))
+         (set sym val))
   :type 'boolean)
 
 (defcustom erc-format-query-as-channel-p t
-- 
2.39.2