From 556d901201c0dbf02fe30656138b32f431429806 Mon Sep 17 00:00:00 2001 From: Ryan Goodrich <207498890+southpawriter02@users.noreply.github.com> Date: Mon, 9 Feb 2026 12:53:26 -0700 Subject: [PATCH 1/6] Expand the "Handling compatibility breakages" section --- engine/guidelines/index.rst | 43 ++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index ea96eb6..fb2766c 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -21,6 +21,43 @@ This section explains guidelines for contributing to the engine. Handling compatibility breakages -------------------------------- -.. TODO: Elaborate on types of compatibility and procedure. - -See also the `current documentation for compatibility breakages `_. +Godot follows a **major.minor.patch** versioning scheme, and each level carries +different expectations around compatibility: + +- **Patch releases** (e.g. 4.3.1 to 4.3.2) must not break compatibility at all. + Existing projects, scripts, and GDExtensions should continue to work without + any changes. +- **Minor releases** (e.g. 4.3 to 4.4) aim to preserve compatibility, but small, + targeted breakages may occur in specific areas when necessary to fix + high-priority issues. The vast majority of projects should not be affected. +- **Major releases** (e.g. 4.x to 5.0) may introduce significant compatibility + breakages that require porting work. + +When contributing changes to the engine, two types of compatibility matter: + +- **Binary compatibility**: Existing compiled binaries (including GDExtensions) + load and execute correctly without recompilation, and their runtime behavior + does not change. +- **Source compatibility**: Existing source code (scripts, scenes, and + GDExtension source) compiles and runs without modification after upgrading + Godot. + +If your change modifies a method signature in any way (even adding an optional +parameter with a default value), you must implement a **GDExtension compatibility +method**. Most language bindings use raw method pointers and handle +default parameters in the binding itself, so even seemingly backward-compatible +signature changes break existing binaries. + +The CI validation system checks for these breakages automatically. If a function +has changed and no compatibility method exists, validation fails with a +"Hash changed" error and a nonzero exit code. + +.. note:: + + Reviewers and area maintainers examine PRs with the ``breaks compat`` label + more closely, checking whether the breakage is justified and whether the + compatibility methods are correctly implemented. + +For the full technical details on implementing compatibility methods, handling +removed or renamed methods, and the GDExtension compatibility promise, see the +`current documentation for compatibility breakages `_. From 277efe6f992a10de7b3018389f81fa246c856668 Mon Sep 17 00:00:00 2001 From: Ryan Goodrich <207498890+southpawriter02@users.noreply.github.com> Date: Mon, 9 Feb 2026 15:36:40 -0700 Subject: [PATCH 2/6] Update engine/guidelines/index.rst Co-authored-by: Lukas Tenbrink --- engine/guidelines/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index fb2766c..61d1b36 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -49,8 +49,7 @@ default parameters in the binding itself, so even seemingly backward-compatible signature changes break existing binaries. The CI validation system checks for these breakages automatically. If a function -has changed and no compatibility method exists, validation fails with a -"Hash changed" error and a nonzero exit code. +has changed and no compatibility method exists, the pull request cannot be merged. .. note:: From 446e28d3e7e9741af3a30dd673259c57e5d9f25e Mon Sep 17 00:00:00 2001 From: Ryan Goodrich <207498890+southpawriter02@users.noreply.github.com> Date: Mon, 9 Feb 2026 15:57:58 -0700 Subject: [PATCH 3/6] Shorten GDExtension compatibility section and inline the docs link --- engine/guidelines/index.rst | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index fb2766c..5251fba 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -42,22 +42,14 @@ When contributing changes to the engine, two types of compatibility matter: GDExtension source) compiles and runs without modification after upgrading Godot. -If your change modifies a method signature in any way (even adding an optional -parameter with a default value), you must implement a **GDExtension compatibility -method**. Most language bindings use raw method pointers and handle -default parameters in the binding itself, so even seemingly backward-compatible -signature changes break existing binaries. - -The CI validation system checks for these breakages automatically. If a function -has changed and no compatibility method exists, validation fails with a -"Hash changed" error and a nonzero exit code. +If your change adds a parameter to a method, changes a return type, changes the +type of a parameter, or alters a default value, you need to implement a +`GDExtension compatibility method `_. +The CI validation system checks for this automatically, and the pull request +cannot be merged until it passes. .. note:: Reviewers and area maintainers examine PRs with the ``breaks compat`` label more closely, checking whether the breakage is justified and whether the compatibility methods are correctly implemented. - -For the full technical details on implementing compatibility methods, handling -removed or renamed methods, and the GDExtension compatibility promise, see the -`current documentation for compatibility breakages `_. From d566f56ef5311b0d8cabcf70b69830d0404ab785 Mon Sep 17 00:00:00 2001 From: Ryan Goodrich <207498890+southpawriter02@users.noreply.github.com> Date: Mon, 9 Feb 2026 17:43:07 -0700 Subject: [PATCH 4/6] Update engine/guidelines/index.rst Co-authored-by: Lukas Tenbrink --- engine/guidelines/index.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index 5251fba..a38263d 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -24,14 +24,11 @@ Handling compatibility breakages Godot follows a **major.minor.patch** versioning scheme, and each level carries different expectations around compatibility: -- **Patch releases** (e.g. 4.3.1 to 4.3.2) must not break compatibility at all. - Existing projects, scripts, and GDExtensions should continue to work without - any changes. -- **Minor releases** (e.g. 4.3 to 4.4) aim to preserve compatibility, but small, - targeted breakages may occur in specific areas when necessary to fix - high-priority issues. The vast majority of projects should not be affected. -- **Major releases** (e.g. 4.x to 5.0) may introduce significant compatibility - breakages that require porting work. +Maintainers generally control what kind of feature is merged at which part of the dev cycle. That being said, you can expect the following kinds of changes to be merged per version: + +- **Patch releases** (e.g. 4.3.1 to 4.3.2) should not break compatibility at all. +- **Minor releases** (e.g. 4.3 to 4.4) should generally not break compatibility, except to fix bugs. New features are added in backwards-compatible ways. +- **Major releases** (e.g. 4.x to 5.0) are rare and can include major changes that break compatibility. When contributing changes to the engine, two types of compatibility matter: From d5fe0b4f0746cb2fd7b837b1ae2984799fb21cb8 Mon Sep 17 00:00:00 2001 From: Ryan Goodrich <207498890+southpawriter02@users.noreply.github.com> Date: Sun, 15 Feb 2026 13:42:03 -0700 Subject: [PATCH 5/6] Update index.rst Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- engine/guidelines/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index a38263d..950168f 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -24,7 +24,8 @@ Handling compatibility breakages Godot follows a **major.minor.patch** versioning scheme, and each level carries different expectations around compatibility: -Maintainers generally control what kind of feature is merged at which part of the dev cycle. That being said, you can expect the following kinds of changes to be merged per version: +Maintainers generally control what kind of feature is merged at which part of the dev cycle. +That being said, you can expect the following kinds of changes to be merged for each version: - **Patch releases** (e.g. 4.3.1 to 4.3.2) should not break compatibility at all. - **Minor releases** (e.g. 4.3 to 4.4) should generally not break compatibility, except to fix bugs. New features are added in backwards-compatible ways. From 86d703e2482e5019c52b4d281ee584ae17b2c4be Mon Sep 17 00:00:00 2001 From: Ryan Goodrich <207498890+southpawriter02@users.noreply.github.com> Date: Tue, 17 Feb 2026 08:10:06 -0700 Subject: [PATCH 6/6] Remove confusing definitions again Removed some very confusing high-level definitions. --- engine/guidelines/index.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index 950168f..2ae0f5d 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -31,15 +31,6 @@ That being said, you can expect the following kinds of changes to be merged for - **Minor releases** (e.g. 4.3 to 4.4) should generally not break compatibility, except to fix bugs. New features are added in backwards-compatible ways. - **Major releases** (e.g. 4.x to 5.0) are rare and can include major changes that break compatibility. -When contributing changes to the engine, two types of compatibility matter: - -- **Binary compatibility**: Existing compiled binaries (including GDExtensions) - load and execute correctly without recompilation, and their runtime behavior - does not change. -- **Source compatibility**: Existing source code (scripts, scenes, and - GDExtension source) compiles and runs without modification after upgrading - Godot. - If your change adds a parameter to a method, changes a return type, changes the type of a parameter, or alters a default value, you need to implement a `GDExtension compatibility method `_.