diff --git a/engine/guidelines/index.rst b/engine/guidelines/index.rst index ea96eb6..2ae0f5d 100644 --- a/engine/guidelines/index.rst +++ b/engine/guidelines/index.rst @@ -21,6 +21,24 @@ This section explains guidelines for contributing to the engine. Handling compatibility breakages -------------------------------- -.. TODO: Elaborate on types of compatibility and procedure. +Godot follows a **major.minor.patch** versioning scheme, and each level carries +different expectations around compatibility: -See also the `current documentation for compatibility breakages `_. +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. +- **Major releases** (e.g. 4.x to 5.0) are rare and can include major changes that break compatibility. + +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.