change log and doc fixes

CHANGES.rst

@@ -7,7 +7,7 @@ Unreleased
 
 -   ``get_parameter_source()`` is available during eager callbacks and type
     conversion again. :issue:`3458` :issue:`3484`
--   Zsh completion scripts parse correctly on Windows. :issue:`3277`
+-   Zsh completion scripts parse correctly on Windows. :issue:`3277` :pr:`3466`
 -   Shell completion of `Choice` `Enum` values produces a valid completion
     result. :issue:`3015`
 -   Fix empty byte-string handling in echo. :issue:`3487`
@@ -53,8 +53,8 @@ Released 2026-05-17
     to be set explicitly. :issue:`2012` :pr:`3363`
 -   The error hint now uses :meth:`Command.get_help_option_names` to pick
     non-shadowed help option names, so ``Try '... -h'`` no longer points to a
-    subcommand option that shadows ``-h``. All surviving names are shown
-    (``-h/--help``). :issue:`2790` :pr:`3208`
+    subcommand option that shadows ``-h``. The longest surviving name is
+    shown (``--help`` over ``-h``) for readability. :issue:`2790` :pr:`3208`
 -   Fix readline functionality on non-Windows platforms. Prompt text is now
     passed directly to readline instead of being printed separately, allowing
     proper backspace, line editing, and line wrapping behavior. :issue:`2968`
@@ -70,8 +70,7 @@ Released 2026-05-17
     fail. :issue:`3105` :pr:`3211`
 -   Add ``click.get_pager_file`` for file-like access to an output
     pager. :pr:`1572` :pr:`3405`
--   :class:`~click.formatting.TextWrapper` and
-    :func:`~click.formatting.wrap_text` now measure line width in visible
+-   :func:`~click.formatting.wrap_text` now measures line width in visible
     characters, ignoring ANSI escape sequences. :pr:`3420`
 -   Fix :meth:`HelpFormatter.write_usage` emitting only a blank line when
     called without ``args``. The usage prefix and program name are now
@@ -87,7 +86,7 @@ Released 2026-05-17
     via :func:`os.dup2` so output that bypasses ``sys.stdout`` (stale stream
     references, C extensions, subprocesses, ``faulthandler``) is captured
     with proper isolation. :issue:`854` :issue:`2412` :issue:`2468`
-    :issue:`2497` :issue:`2761` :issue:`2827` :issue:`2865`
+    :issue:`2497` :issue:`2761` :issue:`2827` :issue:`2865` :pr:`3391`
 -   Revert the ``8.3.3`` change that exposed the original file descriptor
     via ``fileno()`` on the redirected ``CliRunner`` streams in the default
     capture mode. ``os.dup2(w, sys.stdout.fileno())`` calls inside a CLI no

docs/api.md

@@ -283,6 +283,10 @@ classes and functions.
 .. autoexception:: FileError
 ```
 
+```{eval-rst}
+.. autoexception:: NoSuchCommand
+```
+
 ```{eval-rst}
 .. autoexception:: NoSuchOption
 ```

docs/options.md

@@ -563,7 +563,7 @@ own help text.
 
 When several options in a group resolve their values simultaneously, only one
 wins the parameter slot. The full arbitration policy (source precedence,
-explicit-beats-auto tie-break, first-declared fallback) is enumerated under
+explicit-beats-auto tie-break, last-declared fallback) is enumerated under
 [Option value resolution](#option-value-resolution).
 
 ## Option value resolution
@@ -621,6 +621,12 @@ The first source that produces a value wins. Environment variables and
 `default_map` entries set to `Sentinel.UNSET` are skipped, so they fall through
 to the next source rather than supplying `UNSET` to the function.
 
+If after the four sources above no explicit value was found (or only a
+`default_map`/`default` value was) and the option declares `prompt=`, Click
+prompts the user for one. The resulting value is recorded as
+{attr}`ParameterSource.PROMPT`, which ranks above every source listed above
+for arbitration purposes (see [Slot arbitration](#slot-arbitration)).
+
 ### Slot arbitration
 
 Several options can target the same `name` to form a feature switch group. When

src/click/core.py

@@ -2758,7 +2758,7 @@ class Option(Parameter):
     :param hidden: hide this option from help outputs.
     :param attrs: Other command arguments described in :class:`Parameter`.
 
-    .. versionchanged:: 8.4
+    .. versionchanged:: 8.4.0
         Non-basic ``flag_value`` types (not ``str``, ``int``, ``float``, or
         ``bool``) are passed through unchanged instead of being stringified.
         Previously, ``type=click.UNPROCESSED`` was required to preserve them.

src/click/exceptions.py

@@ -249,7 +249,10 @@ def format_message(self) -> str:
 
 
 class NoSuchCommand(UsageError):
-    """Raised if Click attempted to handle a command that does not exist."""
+    """Raised if Click attempted to handle a command that does not exist.
+
+    .. versionadded:: 8.4.0
+    """
 
     def __init__(
         self,

src/click/formatting.py

@@ -53,7 +53,7 @@ def wrap_text(
     :param preserve_paragraphs: if this flag is set then the wrapping will
                                 intelligently handle paragraphs.
 
-    .. versionchanged:: 8.4
+    .. versionchanged:: 8.4.0
         Width is measured in visible characters. ANSI escape sequences in
         ``text``, ``initial_indent``, or ``subsequent_indent`` no longer
         count toward the width budget, so styled input wraps based on what

src/click/shell_completion.py

@@ -423,7 +423,7 @@ def get_completion_args(self) -> tuple[list[str], str]:
 
     def format_completion(self, item: CompletionItem) -> str:
         """
-        .. versionchanged:: 8.4
+        .. versionchanged:: 8.4.0
             Escape newlines in value and help to fix completion errors with
             multi-line help strings.
         """

src/click/termui.py

@@ -305,7 +305,7 @@ def get_pager_file(
 
     Yields a writable file-like object which can be used as an output pager.
 
-    .. versionadded:: 8.2
+    .. versionadded:: 8.4.0
 
     :param color: controls if the pager supports ANSI colors or not.  The
                   default is autodetection.

src/click/types.py

@@ -50,6 +50,12 @@ class ParamType(t.Generic[ParamTypeValue], abc.ABC):
     -   It must be able to convert a value if the ``ctx`` and ``param``
         arguments are ``None``. This can occur when converting prompt
         input.
+
+    .. versionchanged:: 8.4.0
+        Now a generic abstract base class. Parameterize with the
+        converted value type (``ParamType[int]`` for an integer-returning
+        type) so that :meth:`convert` and downstream consumers carry the
+        narrowed return type.
     """
 
     is_composite: t.ClassVar[bool] = False
@@ -264,6 +270,11 @@ class Choice(ParamType[ParamTypeValue], t.Generic[ParamTypeValue]):
     :param case_sensitive: Set to false to make choices case
         insensitive. Defaults to true.
 
+    .. versionchanged:: 8.4.0
+        Now generic in the choice value type. Parameterize with the type of
+        the choice values (``Choice[HashType]`` for an enum, ``Choice[str]``
+        for plain strings) to enable type-checked consumers.
+
     .. versionchanged:: 8.2.0
         Non-``str`` ``choices`` are now supported. It can additionally be any
         iterable. Before you were not recommended to pass anything but a list or