Deprecation policy/Until 2017

Over time, the MediaWiki code base has changed quite a bit. It was originally written during the days of PHP4, which lacked some of the object-oriented niceties in PHP5. Also, as the code base matures, things naturally get refactored and moved around.

Sometimes in the course of writing the software, it is necessary to deprecate a particular function or hook from the software. The following guide is written for these times.

Things to consider when wanting to deprecate something

• How used is it? Is it just 1 or 2 calls in core MediaWiki, or is it used in 30 different extensions?
• Is there an acceptable alternative? If you're deprecating fooBar(), is there a barFoo() that accomplishes the same? Especially important if you're deprecating a still-used interface
• ???

Searching in existing codebases can be achieved with GitHub search feature or with grep for instance, and the popularity of extensions impacted by a change can be assessed with WikiApiary.com for instance.

Antipatterns

• Sometimes deprecations are used as a way to shift the burden of coordination work on someone else's shoulders: phabricator:T127233#2269563.

How to deprecate a PHP method, function, etc.

There are two things that should be added to code when it is deprecated.

1. First it needs to be marked as such in the source code with comments (typically, adding @deprecated to the function's docblock), and all callers should be fixed.
2. At the same time or preferably at a later time it also should be marked with wfDeprecated(). This will throw errors to any developers still using the code. All callers (in extensions and core) should have since been fixed, but this helps weed out stragglers over the next version. The first argument should be __METHOD__ to use the name of the method in the deprecation. Or more detailed text if you are deprecating just a small chunk of code. The second argument must be the version of MediaWiki you are deprecating the method in. This will allow deprecations to be filtered and also tracked. For example:

/**
* @deprecated since 1.22, use Bar
* @return boolean
*/
public static function Foo() {
	wfDeprecated( __METHOD__, '1.22' );
	return self::Bar();
}

In a future MediaWiki version (in this example 1.23 or later), the offending bit of code may be removed.

Deprecations of MediaWiki core functionality should be flagged for a minimum of two MediaWiki releases before removal (except in extreme circumstances). For example, if core is currently version 1.24alpha, then you can proposed deprecating it from MediaWiki 1.24, with removal scheduled for MediaWiki 1.26 or later. You must note breaking changes in the RELEASE_NOTES file, and should inform the wikitech-l and mediawiki-l.

Obviously, you should fix extensions and sample code to not use the functionality in the meantime.

How to deprecate a hook

Deprecating a hook is different, because you want any code that handles the hook to issue a deprecation warning. So at the invocation of Hooks::run( 'Foo', ...) (or the earlier form wfRunHooks( 'Foo', ...):

• Pass the MediaWiki version in which hook Foo is deprecated as the $deprecatedVersion parameter.
• Add a comment afterwards // NOTE: deprecated hook. What to do instead

There is some other cleanup to do:

• Document the hook Foo as "DEPRECATED" in docs/hooks.txt, explain what to do instead.
• Add {{Deprecated|1.NN}} to the Manual:Hooks/Foo page.
• Add "Note this hook is obsolete since MediaWiki 1.NN" to the Category:Foo_extensions page.
• Update Manual:Hooks tables to indicate the hook is deprecated/obsolete since MediaWiki version 1.NN.

Links

• Requests for comment/Deprecation policy - (in-draft as of December 2016) policy related to MediaWiki PHP core
• Phabricator board "Technical Debt" - there is a column "Deprecate / Remove" with proposals for deprecation