Deprecated MediaWiki extension API functions should be moved to a compatibility library instead of being dropped entirely
Open, Needs TriagePublic
Actions

Assigned To

None

Authored By

	Carlb
	Nov 1 2016, 6:35 PM

Description

The pattern has gone on for years... MediaWiki provides some function like wfGetIP() or the wfMsg() series that looks vaguely useful to extension developers, a coder uses the functions in good faith to create a third-party extension which is deployed to some tiny corner of the wiki community and then forgotten, only for subsequent MediaWiki versions to deprecate and eventually delete the once-useful functions and replace them with something else.

No one notices until one of the affected sites attempts to switch to the current MW version and everything breaks in an HTTP 500 size pile of cybernetic wreckage. The hapless sysadmin goes online to search, only to find gems like T70750 "Some poor extensions are so neglected by their parents that still have some of the ugliest wfMsg* stuff which was deprecated in 1.18," Basically, the inference is that it's somehow the extension author's fault that some change to core MediaWiki code breaks things?

If these were extensions written by MediaWiki's core developers, were in WMF version control and/or actively deployed to WMF-operated websites, well, maybe... but there are many other extensions out there which are entirely third-party. Some were cobbled together by independent webmasters to keep their own wiki sites up and running, then promptly forgotten. Some were provided by authors of third-party services (such as CAPTCHA servers, spam blacklists or content distribution networks) who primarily serve non-wiki content providers (for instance, Akismet is a spam filter for Wordpress - someone might try to create an MW wrapper extension to kludge it into our environment, but the developers attention is elsewhere as MW isn't their primary market). The extension might be "official" to the provider of some server whose interests are elsewhere and MW support is an afterthought; the extension may be user-supplied or kludged together by an individual user as sysadmin of one tiny site. As these people aren't primarily in the business of supporting MediaWiki full-time, the extensions often become abandonware and won't be fixed if a MediaWiki extension API change breaks them.

At the moment, one of the extensions broken by "removal of deprecated functions" is https://www.mediawiki.org/wiki/Extension:KeyCAPTCHA - the keycaptcha.com service is intended for non-wiki sites (including blogs) and a "MediWiki 1.16-1.18" extension provided on that site by KeyCAPTCHA as an afterthought. The extension works fine until one deploys MediaWiki 1.27, then breaks as wfGetIP() and the wfGetMsg() functions were removed as "deprecated".

I'm sorely tempted to say that we shouldn't have to operate in an environment where the interface between two pieces of code keeps changing - if a function is documented to exist and extension developers are using it in good faith, the next MW versions that come along shouldn't suddenly deprecate it and eventually remove it as this will break code that was using the function.

https://www.mediawiki.org/wiki/Manual:Messages_API#Help_with_replacing_deprecated_wfMsg.2A_functions and http://www.gossamer-threads.com/lists/wiki/mediawiki-cvs/662109 are a partial "it used to work, we broke it" list.

Failing this, I'd propose as an alternative that a "compatibility library" be packaged as an extension. Much like the math functions which were removed from core MediaWiki code can be reinstated by installing [[mw:ExtensionMath]], there should be an extension package which restores this sort of stuff:

# stub functions to restore deprecated wfGetIP() and wfMsg($x) - use this for MW 1.27 and later only
function wfGetIP() 
{
	global $wgRequest;
	return $wgRequest->getIP();
}

function wfMsg($txt)
{
        return wfMessage( $txt )->text();
}

function wfEmptyMsg($key, $message)
{
        return wfMessage( $key )->inContentLanguage()->isBlank();
}

Basically, include_once() and the missing functions come back to life in stub form to keep old extensions which depended upon them up and working. Unfortunately, I'm in no position to create the "compatibility library extension" myself as the only people who know what functions are breaking or targeted to break next are a core group of developers actively working on MediaWiki code. There have been many changes to MediaWiki that have broken old extensions; I don't claim to have a comprehensive list.

T114384 is related, but addresses "public-facing code" used by gadgets and api.php clients. That's valid, but not quite the same issue as breaking the interface between the core MediaWiki code and individual MediaWiki extensions on the servers.