mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2025-12-31 09:49:22 +03:00
113 lines
6.7 KiB
Plaintext
113 lines
6.7 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)
|
|
# This file is distributed under the same license as the Godot Engine package.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
|
#
|
|
#, fuzzy
|
|
msgid ""
|
|
msgstr ""
|
|
"Project-Id-Version: Godot Engine latest\n"
|
|
"Report-Msgid-Bugs-To: \n"
|
|
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
|
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\n"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:4
|
|
msgid "Handling compatibility breakages"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:8
|
|
msgid "So you've added a new parameter to a method, changed the return type, changed the type of a parameter, or changed its default value, and now the automated testing is complaining about compatibility breakages?"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:12
|
|
msgid "Breaking compatibility should be avoided, but when necessary there are systems in place to handle this in a way that makes the transition as smooth as possible."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:16
|
|
msgid "A practical example"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:20
|
|
msgid "These changes are taken from `pull request #88047 <https://github.com/godotengine/godot/pull/88047>`_, which added new pathing options to ``AStarGrid2D`` and other AStar classes. Among other changes, these methods were modified in ``core/math/a_star_grid_2d.h``:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:29
|
|
msgid "To:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:36
|
|
msgid "This meant adding new compatibility method bindings to the file, which should be in the ``protected`` section of the code, usually placed next to ``_bind_methods()``:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:47
|
|
msgid "They should start with an ``_`` to indicate that they are internal, and end with ``_bind_compat_`` followed by the PR number that introduced the change (``88047`` in this example). These compatibility methods need to be implemented in a dedicated file, like ``core/math/a_star_grid_2d.compat.inc`` in this case:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:51
|
|
msgid "core/math/a_star_grid_2d.compat.inc"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:103
|
|
msgid "Unless the change in compatibility is complex, the compatibility method should call the modified method directly, instead of duplicating that method. Make sure to match the default arguments for that method (in the example above this would be ``false``)."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:106
|
|
msgid "This file should always be placed next to the original file, and have ``.compat.inc`` at the end instead of ``.cpp`` or ``.h``. Next, this should be included in the ``.cpp`` file we're adding compatibility methods to, so ``core/math/a_star_grid_2d.cpp``:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:109
|
|
msgid "core/math/a_star_grid_2d.cpp"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:117
|
|
msgid "Finally, the GDExtension API changes need to be recorded. To do this, first compile Godot on the ``master`` branch, and then run it with the ``--dump-extension-api`` flag:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:126
|
|
msgid "This will create a file named ``extension_api.json`` in your current directory. Switch to your feature branch, recompile Godot, and then run it with the ``--validate-extension-api`` flag followed by the path to the ``extension_api.json`` file you just generated:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:135
|
|
msgid "This will generate some lines starting with ``Validate extension JSON`` like so:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:148
|
|
msgid "If you get a ``Hash changed`` error for a method, it means that the compatibility binding is missing or incorrect. Such lines shouldn't be added to the validation file, but fixed by binding the proper compatibility method. Make sure to double-check the following:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:152
|
|
msgid "For the compatibility method (the one whose name ends with the PR number), the argument types, names, and default values must be identical to the version of the method from before your changes."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:154
|
|
msgid "In ``_bind_compatibility_methods()``, argument names provided to the ``D_METHOD()`` macro in ``ClassDB::bind_compatibility_method()`` must be identical to those from the ``ClassDB::bind_method()`` call for the original method."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:157
|
|
msgid "Add these lines, followed by a comment explaining what the API change was and the actions taken to prevent breakage, to a validation file named after the GitHub pull request ID and placed in the folder of the Godot version it would have broken compatibility for."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:160
|
|
msgid "Since this example was for PR #88047, its file name would be ``GH-88047.txt``, and because this was done during the development of 4.3 (thus changing from 4.2), the file would be in the ``misc/extension_api_validation/4.2-stable/`` folder."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:163
|
|
msgid "See below for a complete example of such a file for this PR:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:165
|
|
msgid "misc/extension_api_validation/4.2-stable/GH-88047.txt"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:180
|
|
msgid "And that's it! You might run into a bit more complicated cases, like rearranging arguments, changing return types, etc., but this covers the basics on how to use this system."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/development/handling_compatibility_breakages.rst:183
|
|
msgid "For more information, see `pull request #76446 <https://github.com/godotengine/godot/pull/76446>`_."
|
|
msgstr ""
|