Backward compatibility

This is a proposed MediaWiki development guideline regarding backward compatibility, pending discussion on wikitech-l. Backward compatibility can roughly be summarized as "how well MediaWiki works together with old software versions or old MediaWiki content".

General principles

Keeping compatibility with old versions of MediaWiki, old extensions we support, old browsers and OSes, third-party extensions written for old versions of MediaWiki, old versions of PHP/MySQL/etc., configuration written for old versions of MediaWiki, and so forth is nice if possible, but needs to be weighed against the burden this creates on development. Sometimes the tradeoff is very clear: e.g., as of 2010, we will still have to support IE8 for a long time to come. On the other hand, code for NN4 is so thoroughly useless by now that obviously no one will be hurt if it's dropped. For more subtle issues, general things to keep in mind are:

• If compatibility code has bitrotted and no longer actually works and no one has complained for a long time, you can always remove it, since you're not making anything worse for anyone. If anyone wants to restore compatibility at a later time, they can always get the old code from version history.
• The major reason to remove compat code is when it creates a maintenance burden, so if it's not creating a maintenance burden, there's usually no reason to remove it. For instance, if compat code is just one line somewhere, or it's some self-contained functions or files that can be clearly marked and ignored, there's no reason to remove it unless you're refactoring that code anyway. Remove compat code only when it causes problems or when you're refactoring related code anyway.
• You're a software developer, so you probably use all the latest, shiniest tools. Remember that most people aren't like you, and don't upgrade stuff unless it breaks. People who want to run MediaWiki 1.11 with trunk extensions shouldn't be dismissed as crazy – they just don't want to go through the inconvenience of a software upgrade.
• Breaking backward compatibility means that when people upgrade MediaWiki, it might stop working properly. We want people to upgrade, and the less attention we pay to backward compatibility, the fewer people can easily upgrade. There's a very real cost to neglecting compatibility, and it shouldn't be forgotten.

Compatibility for configuration options

We should not break anyone's LocalSettings.php unless it's really necessary. If someone started using a configuration option in 1.7, then removing support now punishes them for being a long-time user. Their current LocalSettings.php might have been written by a totally different person years ago, and they might not be in a position to fix it themselves. Editing LocalSettings.php can easily break your site if you don't know PHP. So please, only remove support for config options that you're sure very few people use, and only if there's good reason. Don't assume that few people use it just because it's old. If you do have to remove support, make sure to give clear migration instructions in RELEASE-NOTES, preferably comprehensible to people who don't know PHP.

Compatibility with old PHP/database versions

There's an official minimum supported version for PHP and various database backends. This is bumped occasionally. Once we've dropped support for an old version of PHP or a database, everything is basically guaranteed to break due to syntax errors, so feel free to remove all compatibility code for the old version right away if you like. (Although be careful: sometimes PHP claims new features are enabled by default, but they're disabled by default in some Linux distributions.)

Compatibility with old browsers

Any browser with nontrivial market share (as of the end of 2010, this sadly still includes IE6) should be usable for all basic functionality. "Nontrivial" means at least, say, 0.1% (exact details negotiable per feature). Other browsers should support basic functionality if it doesn't cost us anything, but there's no need for anyone to go out of their way to add it unless they want to. It's fine to have advanced standards-based features only available in shiny new browsers if it would be a pain to emulate them, as long as other browsers are still usable. (But make sure you don't blacklist future or current standards-based browsers you haven't heard of – browsers you haven't heard of should default to all standards-based features enabled if possible, to reward them if they're standards-compliant.)

Trunk extensions' compatibility with old MediaWiki versions

Extensions are branched along with MediaWiki, so trunk extensions only have to support current trunk MediaWiki. However, per #General principles, don't break support for old MediaWiki versions unless the compatibility code is causing actual quantifiable problems, because it's nice if users can get the extra features or bug fixes of trunk extensions even if they're still using old MediaWiki. Some extensions' maintainers deliberately maintain compatibility with old MediaWiki versions, and their wishes should be respected in all cases.

Compatibility with old API clients

The bot API is specifically meant to be stable, and possibly has its own stability guidelines somewhere. I don't know, someone else should fill this in.

Compatibility with old third-party extensions

In an ideal world, anything that a third-party extension might call should continue to work across versions. In practice this is impossible, since most of our functions are public and we can't possibly keep all of them stable. At a minimum, try to maintain compatibility with trunk extensions, updating them if they use an API that you've changed or at least informing their maintainers. If the API you're changing is widely used, like for the Linker::make*Link*() rewrite, try to maintain a compatibility layer if possible. Try harder to be compatible when it comes to hooks, since those are really supposed to be stable. But maintainers of nontrivial third-party extensions will realistically have to update them sometimes for new MediaWiki releases.