compat->compatibility, c/e, link mailinglists
← Older revision
Revision as of 17:58, 27 July 2014
Line 1:
Line 1:
{{mbox
{{mbox
| type = warning
| type = warning
−
| text = This is a proposal about Backwards compatibility for MediaWiki development, For details about our more
defacto
standards please have a look at: [[Compatibility]].
+
| text = This is a proposal about Backwards compatibility for MediaWiki development, For details about our more
''de facto''
standards please have a look at: [[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".
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".
Line 8:
Line 8:
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:
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
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.
+
* 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
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.
+
* 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.
+
* 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.
* 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.
Line 23:
Line 23:
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.
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.
−
Compat
issues with "old" or "rarely used" browsers will roughly fall into these categories:
+
Compatibility
issues with "old" or "rarely used" browsers will roughly fall into these categories:
* unimplemented features which fail harmlessly
* unimplemented features which fail harmlessly
** (example: CSS rounded corners -- non-supporting browsers simply show square corners)
** (example: CSS rounded corners -- non-supporting browsers simply show square corners)
Line 30:
Line 30:
* unimplemented or buggy features which explode horribly, but can be worked around by adding workaround code
* 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)
** (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
programatically
+
* 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.)
** (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
* security issues that only affect particular versions of particular browsers
Line 37:
Line 37:
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.
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.)
+
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 ==
== Trunk extensions' compatibility with old MediaWiki versions ==
Line 47:
Line 47:
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.
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.
+
When a change breaking backwards compatibility is made in trunk, it must be announced on the
[https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce
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
[https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
mediawiki-api
]
list.
== Compatibility with old third-party extensions ==
== Compatibility with old third-party extensions ==