Deprecation

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. Over the last year or so though, it's started to follow this sequence (maybe it should be our policy?). It spans 3 releases, generally.

1. In 1.16 you decide to deprecate something. 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. In 1.17, it can 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
3. In 1.18, the offending bit of code can be removed.