Backport API renames to 3.x and deprecate the old ones

[timothyqiu]

Describe the project you are working on

Playing around with 4.0

Describe the problem or limitation you are having in your project

There are many API renames in 4.0:

1. It'll be a hard transition from 3.x to 4.0
2. Cherry-picking 4.0 PRs to 3.x needs extra work due to API renames
3. Badly named 3.x APIs can still disappoint newcomers as it's a long-term supported version

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

Backport API renames to 3.x, deprecating the old ones.

1. People can start the gradual API transition in 3.x versions
2. 3.x C++ APIs is consistent with their 4.0 counterpart, so it won't be a problem when cherry-picking.
3. Old APIs are deprecated instead of removed, so it's still compatible with existing 3.x user code.

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

For example, String.empty() has been renamed to String.is_empty() in 4.0.

• Rename 3.x empty() to is_empty() in both C++ and (GD)script bindings
• Add empty() to (GD)script bindings that prints a deprecation warning in a tool build and forward the call to is_empty()
  • The C++ empty() may also be kept like this for GDNative & gradual transition.
• Mark empty() as depreacted in documentation, or move it to a dedicated "Deprecated" section in String's documentation.

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

Not possible.

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

Not possible to implement.

[Xrayez]

There are a lot of renames in 4.0. What about autocompletion that is going to be polluted with both old and new names? As far as I know, ClassDB does not have ability to mark methods as deprecated, so that they can be properly hidden. Yet ClassDB does have ability to add "compatibility classes" in 3.x. If you were to add "Deprecated" section in documentation, this ClassDB feature likely must be implemented anyway.

Also, core developers have previously said that they would rather focus on 4.0 development. But for some reason or another, there are not a lot of willing contributors in Godot that would like to advance the project to 4.0-stable release. I also had a similar proposal regarding backporting unit tests to 3.x, see #1533, but it got rejected (aka "no consensus").

On the other hand, I totally understand the desire to make Godot robust, stable and sane, due to the same reasons outlined above, since it will probably take a very long time before Godot 4.0 is released.

[YuriSizov]

While the intention is well, I feel that having two sets of APIs under one roof will be extremely confusing to everyone, especially newcomers. Besides, not all API changes were simple renames, some things disappeared or changed their signatures without a rename. Some renames can also be conflicting with existing names. And often renames touch on things which are String-based and duplicating those can be a huge pain.

The benefit for us backporting changes is obvious, but renames are hardly the main problem when we do that. I would much prefer callable changes and similar differences to be ironed out as they take the most time, unlike renames.

[timothyqiu]

I don't think it's necessary to hide deprecated methods in autocompletion. People should be able to do things the old way if they wish. However, if we were able to mark function as deprecated in documentation by modifying ClassDB, as said, we could give autocompletion extra info to display them differently.

With Vulkan, GDScript 2.0, and the API changes, I worry that Godot 3 vs 4 would become another Python 2 vs 3 situation which took years to recover. I hope backporting API renames can start getting the users ready for the upcoming changes, making the transition slightly easier.

[YuriSizov]

There are tools already that handle conversion for simple renames, maybe even for more advanced cases. We don't need to break 3.x with a mixture of APIs to give a better upgrade path for users.

But also, people definitely should not jump from one version to another expecting it to just work, even if with a few renames. We break compatibility in a lot of ways, and things need to be rebuild for that. It is a major release for a reason.

[Xrayez]

I worry that Godot 3 vs 4 would become another Python 2 vs 3 situation which took years to recover.

I think this is just inevitable... GDScript 2.0 in and of itself will going to introduce enough compatibility breakage regardless of API changes, so not sure if it's worth to make the transition slightly easier (for the sake of it?)

In any case, if core developers do decide to make this happen, please don't add WARN_PRINT() to each and every deprecated method, that would be quite annoying, like godotengine/godot#24222! 😅