Merge pull request #10404 from dsnopek/gdextension-version-compatibility

Improve "Version Compatibility" section in "What is GDExtension"

Author: tetrapod00

tutorials/scripting/gdextension/what_is_gdextension.rst

@@ -24,15 +24,8 @@ you should choose depends on your needs.
 
 .. warning::
 
-    Our long-term goal is that GDExtensions targeting an earlier version of
-    Godot will work in later minor versions, but not vice-versa. For example, a
-    GDExtension targeting Godot 4.2 should work just fine in Godot 4.3, but one
-    targeting Godot 4.3 won't work in Godot 4.2.
-
-    However, GDExtension is currently *experimental*, which means that we may
+    GDExtension is currently *experimental*, which means that we may
     break compatibility in order to fix major bugs or include critical features.
-    For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
-    4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`).
 
 Advantages of GDExtension
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -111,13 +104,26 @@ The bindings below are developed and maintained by the community:
 Version compatibility
 ---------------------
 
-GDExtension add-ons compiled for a given Godot version are only guaranteed to work
-with the same minor release series. For example, a GDExtension add-on compiled for
-Godot 4.0 will only work with Godot 4.0, 4.0.1, 4.0.2. In addition, GDExtension is
-not compatible with Godot 3.x.
+Usually, GDExtensions targeting an earlier version of Godot will work in later
+minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2
+should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
+
+For this reason, when creating GDExtensions, you may want to target the lowest version of
+Godot that has the features you need, *not* the most recent version of Godot. This can
+save you from needing to create multiple builds for different versions of Godot.
 
-GDExtension add-ons are also only compatible with engine builds that use the
+However, GDExtension is currently *experimental*, which means that we may
+break compatibility in order to fix major bugs or include critical features.
+For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
+4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`).
+
+GDExtensions are also only compatible with engine builds that use the same
 level of floating-point precision the extension was compiled for. This means
 that if you use an engine build with double-precision floats, the extension must
-also be compiled for double-precision floats. See
-:ref:`doc_large_world_coordinates` for details.
+also be compiled for double-precision floats and use an ``extension_api.json``
+file generated by your custom engine build. See :ref:`doc_large_world_coordinates`
+for details.
+
+Generally speaking, if you build a custom version of Godot, you should generate an
+``extension_api.json`` from it for your GDExtensions, because it may have some differences
+from official Godot builds.