[PATCH] Documentation: add migration guide for v2025.05.0

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

To simplify barebox updates, let's commit to the documentation a guide
about potential breakage that users and integrators may run into after
an update, e.g. renamed Kconfig symbols.

This is inspired by the migration guides of the Yocto project[1].

[1]: https://docs.yoctoproject.org/3.4/migration-guides/migration-3.4.html

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/index.rst                       |  1 +
 Documentation/migration-guides/index.rst      | 13 ++++
 .../migration-guides/migration-2025.05.0.rst  | 71 +++++++++++++++++++
 3 files changed, 85 insertions(+)
 create mode 100644 Documentation/migration-guides/index.rst
 create mode 100644 Documentation/migration-guides/migration-2025.05.0.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index a3e019e9f0a2..e03f7f7ee946 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -20,6 +20,7 @@ Contents:
    glossary
    devicetree/*
    devel/devel.rst
+   migration-guides/index
    talks
 
 * :ref:`search`
diff --git a/Documentation/migration-guides/index.rst b/Documentation/migration-guides/index.rst
new file mode 100644
index 000000000000..fbe7a0205980
--- /dev/null
+++ b/Documentation/migration-guides/index.rst
@@ -0,0 +1,13 @@
+Release Migration Guides
+========================
+
+Each document in this chapter provides information about how to move to one
+release of barebox from the previous one.
+
+The goal is to help integrators and users of barebox to adapt their
+configuration and downstream board support. barebox API breakage that
+cause build errors are generally out-of-scope for these documents.
+
+.. toctree::
+
+   migration-2025.05.0
diff --git a/Documentation/migration-guides/migration-2025.05.0.rst b/Documentation/migration-guides/migration-2025.05.0.rst
new file mode 100644
index 000000000000..fe734a2921e5
--- /dev/null
+++ b/Documentation/migration-guides/migration-2025.05.0.rst
@@ -0,0 +1,71 @@
+Release v2025.05.0
+==================
+
+Configuration options
+---------------------
+
+* ``CONFIG_CMD_NFS`` and the ``nfs`` command have been removed.
+  Users should use the NFS filesystem implementation instead via
+  :ref:`command_mount`.
+
+* ``CONFIG_STORAGE_BY_UUID`` has been renamed to ``CONFIG_STORAGE_BY_ALIAS``.
+  No functional change for the ``diskuuid`` binding use-case.
+
+* ``CONFIG_ROOTWAIT_BOOTARG`` is now enabled by default and will instruct
+  barebox to append ``rootwait`` when booting from SD/eMMC/USB/NFS if
+  barebox is already configured to generate the ``root=`` option dynamically.
+
+  This can be customized via setting the ``global`` ``linux.rootwait``
+  variable or by disabling the option.
+
+Bootloader Specification
+------------------------
+
+* Special handling for ``devicetree none`` has been finally removed in the
+  bootloader specification parser after triggering an error message for 4 years.
+  To migrate, remove the line.
+
+* GPT partitions with ``DPS_TYPE_FLAG_NO_AUTO`` are now ignored in accordance
+  with the UAPI discoverable partition specification.
+
+* All XBOOTLDR partitions (without ``DPS_TYPE_FLAG_NO_AUTO``) are now
+  considered for bootloader spec files.
+
+  Previously only the first partition with the XBOOTLDR partition type
+  was considered.
+
+* The XBOOTLDR GPT Partition Type UUID is now parsed and handled
+  identically to the MBR partition type.
+
+  If an XBOOTLDR partition exists, barebox will no longer walk
+  all partitions to find further
+  bootloader spec entries.
+
+* Any existing ESP partitions are now searched for entries after
+  XBOOTLDR partitions if any and before iterating over the full
+  list of partitions.
+
+Board support
+-------------
+
+* Legacy STM32MP1 images have been finally dropped from barebox after
+  having been removed from TF-A in 2022.
+
+  Users should migrate to FIP images with barebox as nontrusted firmware
+  (BL33) and the barebox device tree as hardware config.
+
+  Use of multiple device trees is not support directly by the FIP format
+  and can be substituted by a barebox image embedding multiple device trees
+  and using the hardware config FIP slot only as dummy.
+  See the lxa-tac board for an example.
+
+Shell and magic variables
+-------------------------
+
+* ``/dev/fw_cfg0`` has been renamed to ``/dev/fw_cfg``
+
+* ``global.boot.default`` is now ``bootsource net`` by default.
+
+  This does not affect users setting ``nv boot.default``, but for
+  others, barebox will look for bootloader spec on the bootsource
+  medium first.
-- 
2.39.5