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.
Generally, we haven't had an official policy on how to deprecate things, it just happens.

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.