Print an error message pointing to the renamed function when trying to use a function with its old name

[Calinou]

Describe the project you are working on

The Godot editor 🙂

Describe the problem or limitation you are having in your project

Users copy-pasting code from online resources are surprised when the code doesn't work anymore in Godot 4.0, when it did in Godot 3.x. This is because many functions were renamed.

There are many examples of this occurring online, but here's one recent example for demonstration purposes: godotengine/godot#57474

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Print an error message pointing to the renamed function when trying to use a function with its old name. The function's old name should not be reserved – it should still be possible for users to declare functions with the same name as old 3.x functions.

This principle could also be extended to properties, constants and signals, but functions are likely the area where implementing this feature will give the largest ROI in terms of improved usability.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

In each class that has renamed functions, declare a map of functions with their old name and new name.

In the GDScript analyzer, when a function name isn't found, check if the function is part of the rename map on the associated class. If the old name is present in the map's keys, print the new name of the function that should be used.

The check should be enabled in debug builds only to remove any potential performance impact in projects exported in release mode.

If this enhancement will not be used often, can it be worked around with a few lines of script?

Script converters like godotengine/godot#51950 only resolve this problem for existing projects, not new projects where users paste code from outdated online resources.

Not all third-party documentation resources can be updated. Their author may be inactive, the resource may be a physical book, etc.

Is there a reason why this should be core and not an add-on in the asset library?

This needs to be core to be useful to newcomers, who are the most likely to run into this problem.

[jordi-star]

I made a PR demonstrating this in action at godotengine/godot#57520. The functionality is implemented but the map doesn't have any renames in it yet. I'll update the map as I find renamed functions, and I'll open the PR once I think the list is sufficient 👍

If anyone has any renamed functions to add please let me know!

[Calinou]

Now that a project upgrade tool was implemented, its code can probably be reused for this. This would require making the warnings editor-only (rather than also working when trying to run a script in an exported project), but this is probably fine.

[jordi-star]

Done! godotengine/godot#57520 is ready for review.