Remove all deprecations after a set number of minor version updates

[Chubercik]

Just like the title says, this proposal, if implemented, would make all code marked as deprecated have a set lifetime (for example 3 minor versions, which is around a year of Godot development).

As it stands, deprecations get removed during a major version update (e.g. Godot 3 -> Godot 4). This is in line with semantic versioning, but it comes at the cost of having to bundle dead code with the engine.

[dalexeev]

I don't think we should remove all APIs that are deprecated, as there are different reasons for deprecation. Some things are deprecated without an alternative (like AnimatedTexture), some are quite difficult to upgrade (like TileMap). However, there are many cases where we replace an API with an equivalent one (String is_valid_identifier() -> is_valid_ascii_identifier()) or superior one (AStarGrid2D size -> region).

If the code is easy to upgrade and the deprecated API is not commonly used or widely covered in tutorials, then I think it makes sense to remove such APIs after N minor versions. For example, in 4.4 release we can add a message "This property will be removed in Godot 4.6" for some deprecated properties. This will give users enough time to upgrade their projects.

[AThousandShips]

This would require changing our release policy so it's pretty risky, and most deprecation should involve replacing code with delegation meaning the "dead" code is usually very minimal for things I'd say would be reasonable to remove (i.e. not deprecated classes or major old code)

If deprecated code isn't needed, and reducing unnecessary size is important, you can always compile with deprecated=False to exclude all deprecated code

[AThousandShips]

So my thoughts are this, first there are two main kinds of deprecated code in the engine:

1. Methods and properties that are subsets of the new feature, or are renames, or similar, where the deprecation is done simply by delegating to the new method, or using _get/_set for the old properties
2. Methods that still have dedicated code or classes that have replacements (or don't have replacements, but they are even more questionable to remove)

The former make up the larger portion of all deprecated code I'd say, but is very tiny, most of it don't take up almost any binary size, but these can be trivially substituted so are the main candidates for removal

The latter are far fewer (I can think of only four classes off the top of my head, AnimatedTexture, TileMap, and the ParallaxBackground/Layer classes), but are far more complicated, and aren't trivially substituted

So my main concern here is that deprecated code isn't just there to make it easy to lazily copy over your project, they are there to reduce the workload and error risks when migrating to newer versions, as well as giving leeway for outdated code and tutorials

I'd argue that the critical users for deprecated code are big projects that seek to have access to new features while not wanting to do major risky rewrites to their existing projects. While TileMapLayer is a direct substitute and it isn't necessarily difficult to migrate, the migration involves a lot of rewritten code to adjust to where and how to access data etc., this makes it a hurdle of both workload and risk of breaking something when upgrading.

In the end the cost of the deprecated code is minimal, if not negligible, but the cost of removing it is pretty major IMO, first of all there's a lot more work to write migration pages and making sure they are correct so people aren't hit by any surprises, especially of the transition is complicated.

So my suggestion would instead be to make the tools for disabling deprecated code more fine grained, instead of the more blunt tool of disabling all deprecated code I'd suggest a system that:

• Allows separating deprecation of different categories, such as:
  • GDExtension bindings (which are generally pretty critical to keep)
  • Methods
  • Properties
  • Classes
• Allows deprecating features based on the version they were deprecated in, so you can pick to only drop things deprecated in 4.0 but keep everything from 4.1 and forward

But I'd say that removing old deprecated code unconditionally is too much of a risk and places too much of a burden on users when upgrading, and with the shorter development cycles we have for 4.x making sure upgrading isn't a major issue is critical as we have much shorter support windows for minor versions

It also makes the threshold for deprecating things higher, discouraging necessary improvements if they require it

Also a quick test with a dev editor build shows that removing deprecated code saves a whopping ~1.3 MB, or 0.82%, and that's all deprecated code, so it's a vanishingly tiny portion, similar results for a release build on windows, ~ 600 MB and %0.93

tl;dr;
If you aren't using any deprecated code you can save a little bit of binary size by using deprecated=False when compiling, but in the end it doesn't cost that much compared to the additional work for developers and users, and makes maintaining projects much harder

[AThousandShips]

To summarize this a bit and add some thoughts to it, I would argue that there are three primary areas where backwards compatibility in general (but in this case of course deprecation in particular) is important or relevant:

1. Re-using existing code (i.e. demos and tutorials or samples) or using plugins, cases where the individual user has no control over the source itself, but is helped by being able to use the code still
2. Projects being developed longer term, where the developers transition between minor versions as they work
3. Long term maintenance of released projects

For 1 the solution would generally be that the author of the existing code or plugin update it, for them they essentially deal with 2, but you also have the benefit of being free from having to maintain separate versions of a plugin if not necessary, supporting both 4.2 and 4.3 by using a method or property deprecated in 4.3 to make it more general

For 2 I'd say a bit of extra work is to be expected when updating and upgrading while you work, and deprecated methods help greatly in that process because you don't just get a bunch of errors but can gradually transition as you work, upgrading a component of the game when you already do work on it for other reasons for example. For this category you should expect some work to upgrade but it should be as smooth as possible and you shouldn't have to do really anything unless you want to access new functionality (except perhaps re-saving files or re-importing resources as needed)

The area I find the most critical is 3 however, due to the support window of Godot versions, and while we aim to support older versions it is done on a best effort and demand basis and eventually older minor versions of 4.x will no longer be supported. While some users maintain their own branches and apply important fixes on their own (either fixing them independently or adapting fixes in the main repo to older versions) that can be a lot of work to maintain a game you already released. Especially if you have a game developed and released with 4.1, and one with 4.3, and later one with 4.5, for example, needing to maintain each individually.

So because even critical security fixes aren't necessarily guaranteed to arrive for older versions there are (and especially will be) games developed and released that are still available using those versions, and to me deprecated features is critical to reduce the workload for safely and responsibly maintaining older games you released. You shouldn't have to pick between not fixing issues in your old games and having to spend a lot of work upgrading your project because there are no easy pathways to do so. As much as possible older projects should be possible to re-export with a later version with minimal work (i.e. a day, or a few days, or work to tweak and re-import and fix, as opposed to weeks and weeks of replacing code and nodes etc.)

So that makes me feel that long term deprecation being available is the most critical, and that IMO deprecation is more important a few years after it was deprecated than immediately after

[dsnopek]

So far, the amount of deprecated code is pretty small and manageable, at least in my opinion. If we keep accruing it at approximately the same rate, I don't think we should really be burdened by it, even after 4-5 years. Of course, that could change, and we could see an increase and a corresponding spike in maintenance cost, but I think we should address it then and not before it becomes an actual problem.