Усунення порушень сумісності
Отже, ви додали новий параметр до методу, змінили тип повернення, змінили тип параметра або змінили його значення за замовчуванням, і тепер автоматизоване тестування скаржиться на порушення сумісності?
Слід уникати порушення сумісності, але за необхідності існують системи, які впораються з цим таким чином, щоб зробити перехід максимально плавним.
Практичний приклад
Ці зміни взято з запиту на витягування #88047, який додав нові параметри шляху до AStarGrid2D та інших класів AStar. Серед інших змін, ці методи були змінені в core/math/a_star_grid_2d.h:
Vector<Vector2> get_point_path(const Vector2i &p_from, const Vector2i &p_to);
TypedArray<Vector2i> get_id_path(const Vector2i &p_from, const Vector2i &p_to);
до:
Vector<Vector2> get_point_path(const Vector2i &p_from, const Vector2i &p_to, bool p_allow_partial_path = false);
TypedArray<Vector2i> get_id_path(const Vector2i &p_from, const Vector2i &p_to, bool p_allow_partial_path = false);
Це означало додавання нових прив’язок методів сумісності до файлу, який повинен бути в розділі protected коду, зазвичай розміщеному поруч з _bind_methods():
#ifndef DISABLE_DEPRECATED
TypedArray<Vector2i> _get_id_path_bind_compat_88047(const Vector2i &p_from, const Vector2i &p_to);
Vector<Vector2> _get_point_path_bind_compat_88047(const Vector2i &p_from, const Vector2i &p_to);
static void _bind_compatibility_methods();
#endif
Вони повинні починатися з символу _, щоб вказати, що вони є внутрішніми, і закінчуватися на _bind_compat_, за яким слідує номер зміни, що ввела зміну (88047 у цьому прикладі). Ці методи сумісності потрібно реалізувати у спеціальному файлі, наприклад, у цьому випадку core/math/a_star_grid_2d.compat.inc:
/**************************************************************************/
/* a_star_grid_2d.compat.inc */
/**************************************************************************/
/* This file is part of: */
/* GODOT ENGINE */
/* https://godotengine.org */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
/* */
/* Permission is hereby granted, free of charge, to any person obtaining */
/* a copy of this software and associated documentation files (the */
/* "Software"), to deal in the Software without restriction, including */
/* without limitation the rights to use, copy, modify, merge, publish, */
/* distribute, sublicense, and/or sell copies of the Software, and to */
/* permit persons to whom the Software is furnished to do so, subject to */
/* the following conditions: */
/* */
/* The above copyright notice and this permission notice shall be */
/* included in all copies or substantial portions of the Software. */
/* */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
/**************************************************************************/
#ifndef DISABLE_DEPRECATED
#include "core/variant/typed_array.h"
TypedArray<Vector2i> AStarGrid2D::_get_id_path_bind_compat_88047(const Vector2i &p_from_id, const Vector2i &p_to_id) {
return get_id_path(p_from_id, p_to_id, false);
}
Vector<Vector2> AStarGrid2D::_get_point_path_bind_compat_88047(const Vector2i &p_from_id, const Vector2i &p_to_id) {
return get_point_path(p_from_id, p_to_id, false);
}
void AStarGrid2D::_bind_compatibility_methods() {
ClassDB::bind_compatibility_method(D_METHOD("get_id_path", "from_id", "to_id"), &AStarGrid2D::_get_id_path_bind_compat_88047);
ClassDB::bind_compatibility_method(D_METHOD("get_point_path", "from_id", "to_id"), &AStarGrid2D::_get_point_path_bind_compat_88047);
}
#endif // DISABLE_DEPRECATED
Якщо зміна сумісності не є складною, метод сумісності повинен викликати модифікований метод безпосередньо, замість того, щоб дублювати цей метод. Переконайтеся, що аргументи за замовчуванням відповідають цьому методу (у прикладі вище це буде false).
Цей файл завжди слід розміщувати поруч із оригінальним файлом і мати .compat.inc у кінці замість .cpp або .h. Далі це слід включити у файл .cpp, до якого ми додаємо методи сумісності, тому core/math/a_star_grid_2d.cpp:
#include "a_star_grid_2d.h"
#include "a_star_grid_2d.compat.inc"
#include "core/variant/typed_array.h"
І, нарешті, зміни, про які повідомляє етап перевірки API, слід додати до відповідного файлу перевірки. Оскільки це було зроблено під час розробки 4.3, це буде misc/extension_api_validation/4.2-stable.expected (включаючи зміни, не показані в цьому прикладі):
GH-88047
--------
Validate extension JSON: Error: Field 'classes/AStar2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar2D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar3D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar3D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Added optional "allow_partial_path" argument to get_id_path and get_point_path methods in AStar classes.
Compatibility methods registered.
Інструкції щодо додавання до цього файлу знаходяться у верхній частині самого файлу.
Якщо ви отримуєте помилку «Хеш змінено» для методу, це означає, що прив’язка сумісності відсутня або неправильна. Такі рядки не слід додавати до файлу .expected, а виправляти шляхом прив’язки належного методу сумісності.
І все! Ви можете зіткнутися з дещо складнішими випадками, як-от перевпорядкування аргументів, зміна типів повернення тощо, але тут охоплюються основи використання цієї системи.
Для отримання додаткової інформації перегляньте запит на витягування #76446.