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  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: T127233.

kyjk

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  (or the earlier form  :
 * Pass the MediaWiki version in which hook Foo is deprecated as the  parameter.
 * Add a comment afterwards

There is some other cleanup to do:
 * Document the hook Foo as "DEPRECATED"  in docs/hooks.txt, explain what to do instead.
 * Add  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