Adopt a policy to remove deprecated functions

[ayeshrajans]

One of the things WordPress is known for is its backwards-compatibility. You can throw WordPress at pretty much any PHP hosting imaginable, there is a very good chance WordPress would run on it.

The same goes for code that integrated with WordPress. Plugins and themes are largely compatible with several WordPress versions.

When we modernize WordPress, we deprecate functionality by moving them to src/wp-includes/deprecated.php or src/wp-admin/includes/deprecated.php files.

Both of these files as a header:

The functions will be removed in a later version.

I checked if we have _ever_ removed a function from these files, and the discoveries were, well, fascinating.

/**
 * Returns or prints a category ID.
 *
 * @since 0.71
 * @deprecated 0.71 Use get_the_category()
 */
function the_category_ID($echo = true) {
...
}

This is the oldest function we still have in WordPress. WordPress 0.71 was released in 2003. There were Concordes flying, George W. Bush was just into his second presidency, first iPhone is revealed 4 years after WordPress 0.71. To put backwards compatibility to perspective, Microsoft, a company known for its good backwards compatibility, stopped support for Windows 7 that was released in 2009.

I think we need to agree to a policy on how long we keep these deprecated functions for. Having functions deprecated 17 years ago still in our code base is clearly an overkill.

We don't use interfaces, abstract classes, or otherwise code-enforced contracts in WordPress (yet?), so the upgrade process for existing user-land code should be pretty easy, as we the deprecation notice often tells the new function to use instead of the deprecated one.

Even if we consider every major (not in a semantic versioning sense) WordPress such as 5.3, 5.4 and 5.5 as LTS version, I have only seen software providing compatibility for upto 5 years (Ubuntu LTS releases for example).

Note that both of these files are included by default, and a routine clean-up means we reword users who update frequently with light-weight code. This is the segment of users that we should reward anyway. If a certain plugin absolutely, must, adamantly, and and uncompromisingly need to use a function, they can poly-fill those functions in the plugins own code based with plugin name prefix. This is not a practice that we should encourage though.

Proposal

We should not be needing to open a ticket every time we need to remove a deprecated function. A policy adopted means we roughly know when and how the deprecated code should be purged.

I would like to propose that we agree to a policy on how long we keep the deprecated functions in the code base, and my personal vote would be 5 years.

5 years is a plenty of time to upgrade existing plugins and themes, and if a theme/plugin did not receive updates for 5 years, there is a very good chance that they have security vulnerabilities and major bugs.

Statistics

To put this 5 year policy to perspective, this leaves WordPress 4.1 and older versions out. Here is a break-down on when functions were deprecated.

Version deprecated in	deprecated.php	admin deprecated.php	total
0.x	2	0	2
1.x	3	0	3
2.x	87	5	92
3.x	57	59	116
4.0	3	0	3
4.1	0	0	0
>4.1	29	8	37
Grand total	181	72	253
Deprecated >5 years ago	152	64	216

This can lead to removal of polyfills (such as the recently removed SPL polyfill) and help us keep up with WordPress and PHP modernization.

[ayeshrajans]

In Git, you can check if there have ever been a removal of a function:

git diff HEAD~10000..HEAD src/wp-includes/deprecated.php

There are line removals (as git diff --numstat) would show, but they are purely line corrections. I could not find any function that was removed with a bisect of all 41,000+ commits in recorded WordPress history (although there is a chance this is not accurate).

[SergeyBiryukov]

Related: #41520, #42897.

[johnbillion]

I'm generally in favour of finding a solution for this and introducing a policy to support it, but we need to identify the problem first.

• What is the problem that we're trying to solve by removing deprecated functions? (eg. Are they unsafe, unperformant, ugly?)
• Does the advantage of removing a deprecated function outweigh the potential to introduce fatal errors if they're being used on live sites?

[jorbin]

Causing a site to fatal simply because it's not using the best practice that a site owner may not know about nor have the skills to easily fix seems cruel to me.

[TimothyBlynJacobs]

Having functions deprecated 17 years ago still in our code base is clearly an overkill.

I think this needs to be expanded to a clearer set of negative impacts to the project by keeping these functions in core.

In my opinion, I think the only reason a function should be removed would be if it had an unfixable serious security issue.

With the push to introduce major version auto updates, introducing further chances of fatal errors seems like it could hamper that effort.

[SergeyBiryukov]

Replying to TimothyBlynJacobs:

With the push to introduce major version auto updates, introducing further chances of fatal errors seems like it could hamper that effort.

I tend to agree.

Adopting a policy for deprecated functions sounds good in theory. However, as long as they don't cause any noticeable performance overhead or maintenance burden, which doesn't seem to be the case now, removing them would only increase the chance of fatal errors on update, without a strong reason.

[johnbillion]

I'd like to expand on some of the comments above, particularly jorbin's, to frame this discussion in a real world scenario.

Imagine a "mom and pop" business that paid for a small website many years ago. The developer who built the site did a good job, and they built a custom plugin for the site. One of the functions they used in this custom plugin has since been deprecated but continues to perform its duty.

The business owners have done as the developer said and kept their plugins and WordPress up to date with new releases over the years. They have better things to do than check their PHP error log for deprecated function warnings, and the custom plugin that they had developed has never been subsequently updated to use the newer APIs.

One day they update to WordPress 5.X which has finally removed this deprecated function, and boom their site comes to a fatal conclusion despite having functioned well for many years prior.

When we talk about fixing problems we must see these problems from the position of the end user, not just developers. What real world problem are we solving by removing deprecated functions? Can that problem ever be so important that it warrants potentially causing a website to go offline?

Unlike developer-facing software I don't think deprecated functions in WordPress can or should be removed.

[JeffPaul]

I concur with the same sentiment as others here, there does not appear to be an actual problem here nor is there benefit in removing deprecated functions (worse, there appears to be a significant likelihood of a negative result for end users). Thus, I'm closing this as wontfix.