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

How to deprecate a method, hook, etc.
There are two things that should be added to code when it is deprecated. First it needs to be marked as such in the source code with comments (typically, adding  to the function's docblock), and all callers should be fixed. 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  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:

In the future such as 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  and.