Umgang mit Kompatibilitätsbrüchen
Sie haben also einen neuen Parameter zu einer Methode hinzugefügt, den Rückgabetyp, den Typ eines Parameters oder seinen Defaultwert geändert, und jetzt beschweren sich die automatisierten Tests über Kompatibilitätsbrüche?
Kompatibilitätsbrüche sollten vermieden werden, aber wenn es notwendig ist, gibt es Systeme, die den Übergang so reibungslos wie möglich gestalten.
Ein praktisches Beispiel
Diese Änderungen stammen aus dem pull request #88047, der neue Pfadoptionen zu AStarGrid2D und anderen AStar-Klassen hinzugefügt hat. Neben anderen Änderungen wurden diese Methoden in core/math/a_star_grid_2d.h modifiziert:
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);
Nach:
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);
Dies bedeutete, dass neue Kompatibilitätsmethoden-Bindings in die Datei aufgenommen werden mussten, die im geschützten Abschnitt des Codes, normalerweise neben _bind_methods(), platziert werden sollten:
#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
Sie sollten mit einem _ beginnen, um anzuzeigen, dass sie intern sind, und mit _bind_compat_ enden, gefolgt von der PR-Nummer, in der die Änderung eingeführt wurde (88047 in diesem Beispiel). Diese Kompatibilitätsmethoden müssen in einer eigenen Datei implementiert werden, wie in diesem Fall 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
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).
Diese Datei sollte immer neben der Originaldatei stehen und am Ende .compat.inc anstelle von .cpp oder .h haben. Als nächstes sollte sie in die Datei .cpp eingefügt werden, der wir Kompatibilitätsmethoden hinzufügen, also 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"
Und schließlich sollten die vom API-Validierungsschritt gemeldeten Änderungen der entsprechenden Validierungsdatei hinzugefügt werden. Da dies während der Entwicklung von 4.3 geschehen ist, wäre dies misc/extension_api_validation/4.2-stable.expected (einschließlich der in diesem Beispiel nicht gezeigten Änderungen):
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.
Die Anweisungen für das Hinzufügen zu dieser Datei befinden sich am Anfang der Datei selbst.
Wenn Sie einen "Hash changed"-Fehler für eine Methode erhalten, bedeutet dies, dass die Kompatibilitätsbindung fehlt oder falsch ist. Solche Zeilen sollten nicht der Datei .expected hinzugefügt werden, sondern durch Bindung der richtigen Kompatibilitätsmethode behoben werden.
Und das war's! Es kann sein, dass Sie auf etwas kompliziertere Fälle stoßen, wie z. B. das Umordnen von Argumenten, das Ändern von Rückgabetypen usw., aber dies deckt die grundlegenden Möglichkeiten der Verwendung dieses Systems ab.
Für weitere Informationen siehe pull request #76446.