Merge pull request #11075 from Ayush41/export_file-breaking-change-doc

Add behavior change note for @export_file annotation in Godot 4.4

Author: skyace65

tutorials/migrating/upgrading_to_godot_4.4.rst

@@ -55,8 +55,27 @@ Method ``post`` adds a new ``count`` optional parameter
 Method ``standardize_locale`` adds a new ``add_defaults`` optional parameter                                              |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-98972`_
 ========================================================================================================================  ===================  ====================  ====================  ============
 
+**Export annotations**
+
+.. warning::
+
+    The behavior of ``@export_file`` changed in Godot 4.4. When assigning a new value
+    from the Inspector, the path is now stored and returned as a ``uid://`` reference
+    instead of the traditional ``res://`` path(`GH-97912`_). This is a **breaking change** and may
+    cause issues if you're expecting ``res://``-based paths in scripts or serialized
+    files.
+
+    For example, exported arrays of files may now contain a mix of ``uid://`` and
+    ``res://`` paths, especially if they were partially edited in the Inspector.
+
+    In 4.4, the only way to retain the ``res://`` format is to **manually edit** the
+    `.tscn` or `.tres` files in a text editor. Starting in Godot 4.5, a new annotation
+    ``@export_file_path`` can be used to explicitly retain the old behavior and export
+    raw ``res://`` paths.
+
 .. [#f1] Default buffer size in 4.3 is ``1024``.
 
+
 GUI nodes
 ~~~~~~~~~
 
@@ -206,6 +225,7 @@ Android
 .. _GH-95212: https://github.com/godotengine/godot/pull/95212
 .. _GH-95126: https://github.com/godotengine/godot/pull/95126
 .. _GH-97449: https://github.com/godotengine/godot/pull/97449
+.. _GH-97912: https://github.com/godotengine/godot/pull/97912
 .. _GH-98670: https://github.com/godotengine/godot/pull/98670
 .. _GH-98918: https://github.com/godotengine/godot/pull/98918
 .. _GH-98972: https://github.com/godotengine/godot/pull/98972