Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions engine/guidelines/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://docs.godotengine.org/en/stable/engine_details/development/handling_compatibility_breakages.html>`_.
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 <https://docs.godotengine.org/en/stable/engine_details/development/handling_compatibility_breakages.html>`_.
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.