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 Netscape 4 is so thoroughly useless by now that obviously no one is hurt by its absence. For more subtle issues, general things to keep in mind are:

• If compatibility code has bit-rotted 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 compatibility 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 compatibility 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 compatibility 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.)

See also: Backward compatibility in database access

Compatibility with old browsers

MediaWiki strives towards standards compatibility with progressive enhancement for newer/rarer optional browser features when available, and graceful degradation for common widely-used features in the face of browsers with more limited capabilities.

Compatibility issues with "old" or "rarely used" browsers will roughly fall into these categories:

• unimplemented features which fail harmlessly
  • (example: CSS rounded corners -- non-supporting browsers simply show square corners)
• unimplemented or buggy features which can be detected
  • (example: upload preview thumbnails -- non-supporting browsers see the missing interface, and don't invoke the code for it)
• unimplemented or buggy features which explode horribly, but can be worked around by adding workaround code
  • (example: CSS layout in IE 6, 7 needs additional rules and code added via conditional comments which only IE reads)
• unimplemented or buggy features which explode horribly, but can't be detected programmatically
  • (this tends to lead to browser sniffing version checks -- which SHOULD be blacklists for known-bad browsers. Whitelists for known-good browsers are problematic and SHOULD NOT be used.)
• security issues that only affect particular versions of particular browsers
  • Generally this means security bugs in IE 6.0 (security bugs in other browsers tend to actually get patched or replaced, whereas IE 6 deployments are generally stuck in a position where they cannot upgrade)

Since it's not possible to test and reason about every conceivable browser ahead of time, actual testing & prioritization of discovered bugs is based roughly on real-world browser popularity.

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

Some extensions are branched along with MediaWiki, so trunk extensions only have to support current trunk MediaWiki. Other extensions try to remain compatible with as many old MediaWiki versions as possible (within limits of practicality). See Compatibility#MediaWiki extensions for checking and documenting which compatibility policy is followed by a given extension. Per #General principles, don't break support for old MediaWiki versions gratuitously.

Compatibility with old API clients

The bot API is specifically meant to be stable. Backwards incompatible changes should only be made for security reasons. Because a certain approach is esthetically more appealing, or a saner way to do something is not a reason to break backwards compatibility.

Backwards compatibility is not required with unreleased trunk revisions; only with release versions. However as the largest MediaWiki installation does not run only on released versions, Wikimedia deployment branches should be considered releases for the purpose of API compatibility.

When a change breaking backwards compatibility is made in trunk, it must be announced on the mediawiki-api-announce mailing list with a subject line like "BREAKING CHANGE: list=foo ignores bar parameter". Messages sent to this list are automatically copied to the mediawiki-api list.

Compatibility with old third-party extensions

Main policy: Deprecation

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.

See also

• Compatibility