Add changelog entry, fix admonition and add test

Author: kdeldycke

CHANGES.rst

@@ -5,6 +5,11 @@ Version 8.4.2
 
 Unreleased
 
+-   Fix Fish shell completion broken in ``8.4.0`` by :pr:`3126`. Newlines and
+    tabs in option help text are now escaped, keeping the original completion
+    format while still supporting multi-line help. :issue:`3502`
+    :issue:`3043` :pr:`3504` :pr:`3508`
+
 
 Version 8.4.1
 -------------

src/click/shell_completion.py

@@ -419,9 +419,9 @@ def get_completion_args(self) -> tuple[list[str], str]:
 
     def format_completion(self, item: CompletionItem) -> str:
         """
-        .. versionchanged:: 8.4.0
-            Escape newlines in value and help to fix completion errors with
-            multi-line help strings.
+        .. versionchanged:: 8.4.2
+            Escape newlines and replace tabs with spaces in the help text to
+            fix completion errors with multi-line help strings.
         """
         # According to https://fishshell.com/docs/current/cmds/complete.html
         # Command substitutions found in ARGUMENTS should return a newline-

tests/test_shell_completion.py

@@ -12,6 +12,7 @@
 from click.core import Option
 from click.shell_completion import add_completion_class
 from click.shell_completion import CompletionItem
+from click.shell_completion import FishComplete
 from click.shell_completion import shell_complete
 from click.shell_completion import ShellComplete
 from click.types import Choice
@@ -576,3 +577,11 @@ def cli(ctx, config_file):
             assert not current_warnings, "There should be no warnings to start"
             _get_completions(cli, args=[], incomplete="")
             assert not current_warnings, "There should be no warnings after either"
+
+
+def test_fish_format_completion_escapes_help():
+    fc = FishComplete(Command("x"), {}, "x", "_X_COMPLETE")
+    item = CompletionItem("--at", help="first\nsecond\tthird")
+    # The newline is escaped to the literal characters backslash-n and the tab
+    # becomes a space, so each completion stays on one line for fish.
+    assert fc.format_completion(item) == "plain,--at\tfirst\\nsecond third"