Document how to handle compatibility breakages

[AThousandShips]

Basic instructions and examples for using this feature

[Bromeon]

Thanks a lot! Sounds good so far, my feedback is very nitpicky 😅

Regarding an example, maybe we should use a real one that occurred? Then we don't need to make up things. It probably illustrates the principle better than an abstract one with "arg1", "arg2" etc.

[dsnopek]

Thanks for starting on this! I look forward to linking to it in the future :-)

[AThousandShips]

Added a concrete example, will go back over the style review as well, and the wording in the new example code isn't perfect, any feedback would be appreciated there

[dsnopek]

Thanks! This is looking really great so far.

[dsnopek]

While this is a totally valid example of an argument being removed, I feel like the reverse case is more common: adding a new argument to method. So, I'd personally reverse these:

Suggested change

	ClassDB::bind_method(D_METHOD("my_method", "arg1", "arg2"), &MyClass::my_method);
	ClassDB::bind_compatibility_method(D_METHOD("my_method", "arg1", "arg2", "arg3"), &MyClass::_my_method_bind_compat_1234, DEFVAL(0));
	ClassDB::bind_method(D_METHOD("my_method", "arg1", "arg2", "arg3"), &MyClass::my_method, DEFVAL(0));
	ClassDB::bind_compatibility_method(D_METHOD("my_method", "arg1", "arg2"), &MyClass::_my_method_bind_compat_1234);

[dsnopek]

This redundantly mentions the "PR number" twice in the same sentence. Maybe:

Suggested change

	Note the ``88047`` at the end of the method names should match the PR number, they should also start with a ``_`` to
	indicate that they are internal, and end with ``_bind_compat`` followed by the PR number. These compatibility methods
	They should start with a ``_`` 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

[dsnopek]

Suggested change

	need to be defined as well, and these were added in a dedicated file, in this case ``core/math/a_star_grid_2d.compat.inc``:
	need to be implemented in a dedicated file, like ``core/math/a_star_grid_2d.compat.inc`` in this case:

[dsnopek]

Suggested change

	And finally the changes reported by the API validation step should be added to the relevant validation file, which because this was
	done during the development of 4.3 would be ``misc/extension_api_validation/4.2-stable.expected`` (including changes not shown in
	And finally, the changes reported by the API validation step should be added to the relevant validation file. Because this was
	done during the development of 4.3, this would be ``misc/extension_api_validation/4.2-stable.expected`` (including changes not shown in

[dsnopek]

Either here, or in the forth-coming instructions above, we should mention that in 99.99% of cases, we shouldn't be ignore the "hash changed" messages. If those don't go away on their own, then the developer will know they did something wrong with the compatibility methods.