From e10b97552e7f1f52de0348097219f33c5a456386 Mon Sep 17 00:00:00 2001
From: Mauricio Villegas <5780272+mauvilsa@users.noreply.github.com>
Date: Tue, 6 Oct 2026 07:50:14 +0200
Subject: [PATCH] Sync v5 migration docs

---
 sphinx/migrate_v5.rst | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/sphinx/migrate_v5.rst b/sphinx/migrate_v5.rst
index 9aaf2132..9bed4e0b 100644
--- a/sphinx/migrate_v5.rst
+++ b/sphinx/migrate_v5.rst
@@ -35,14 +35,12 @@ changes:
 - **``pyyaml`` is no longer a required dependency.** Gives no deprecation
   warning. If your code imports ``yaml``, or you want YAML configs, install with
   the ``yaml`` extra (``pip install "jsonargparse[yaml]"``).
-- **``parser_mode`` defaults to ``json``.** Gives no deprecation warning. Config
-  files and command line values are loaded as JSON instead of YAML, so YAML
-  syntax, e.g. ``key: value`` configs, ``--list=[a, b]`` or ``--flag=yes``,
-  fails. To keep YAML, give ``parser_mode="yaml"`` to the parser, which also
-  works in v4, or set it globally with
-  ``set_parsing_settings(parser_mode="yaml")`` or the
-  ``JSONARGPARSE_PARSER_MODE=yaml`` environment variable. The ``jsonnet`` parser
-  mode no longer accepts YAML either.
+- **``parser_mode`` defaults to ``json_or_yaml``.** Gives no deprecation
+  warning. Config files and command line values are parsed as JSON, and only if
+  that fails as YAML, so with the ``yaml`` extra installed YAML keeps working.
+  Without it, YAML syntax, e.g. ``key: value`` configs or ``--list=[a, b]``,
+  fails. For strict JSON, give ``parser_mode="json"`` to the parser, which also
+  works in v4.
 - **``json`` dumps are now indented.** Gives no deprecation warning.
   ``dump(format="json")``, ``save`` and the print config argument produce
   indented JSON instead of a single line. Use ``format="json_compact"`` for the
@@ -77,12 +75,13 @@ changes:
   ``instantiate`` gives a :func:`functools.partial` with the arguments bound, or
   an :func:`operator.methodcaller` for a method that is called with an instance,
   instead of the parsed namespace. Call it, e.g. ``init.fn()`` instead of
-  ``fn(**init.fn)``, or give ``instantiate=False`` to keep the namespace. Warns
-  only with ``JSONARGPARSE_DEPRECATION_WARNINGS=all``.
+  ``fn(**init.fn)``, or in v5 give ``instantiate=False`` to keep the namespace.
+  Warns only with ``JSONARGPARSE_DEPRECATION_WARNINGS=all``.
 - **Abbreviated options are disabled.** ``allow_abbrev`` defaults to ``False``,
   so e.g. ``--max`` no longer matches ``--max_epochs``. Use full option names,
-  or keep abbreviations with ``allow_abbrev=True`` in the parser, or globally
-  with ``set_parsing_settings(allow_abbrev=True)`` or the
+  or keep abbreviations with ``allow_abbrev=True`` in the parser, which also
+  works in v4, or in v5 globally with
+  ``set_parsing_settings(allow_abbrev=True)`` or the
   ``JSONARGPARSE_ALLOW_ABBREV=true`` environment variable.