On Fri, Sep 2, 2011 at 7:40 AM, Niklas Laxström niklas.laxstrom@gmail.comwrote:
Having said that, I think BC is important and we should continue be as strict about it as we have been. The current practice seems to be:
- keep the old interface available unless it makes no sense anymore
- add @deprecated in X, warnings in X+2, removed in X+4 where X is
the current development version, the numbers may wary a little 3) update all extensions in the svn to use the new interface (with exception, see rest of this message) 4) add warnings and remove in version stated in 2)
Generally speaking, we should only throw warnings or remove old interfaces that are actively broken (do not work correctly) or can no longer be sanely maintained -- removing a deprecated interface is a fairly extreme step and should never be done just to make things look cleaner.
There may be little or even *negative* benefit to going around and changing all the calling code to use the new interface. I've seen *lots* of regressions in commits that swap something to a new interface without taking into account how the interface actually changed, and they're harder to track down because the changes are often buried in generic code clean-up.
Instead of just updating the code of those extensions to the new interface directly, right now we have to add conditions like if ( foo ) { do_it_the_new_way() } else { do_it_the_old_way() }. or use more convoluted mechanisms. Without coordination different people make different solutions.
Updating code to use newer interfaces is only actually needed if there's an advantage to using the new interface, such as better performance or higher capabilities. If you don't need it, you can and maybe should just keep using the old interface!
It doesn't hurt to leave an explicit comment saying why you're using an older interface for compatibility, of course, so some smart guy doesn't come along and replace all your calls with the new interface. ;)
So old extension code *should* just keep on working on new versions in the vast majority of cases; conditional use is only relevant if you actually need the different capabilities or performance characteristics... an example is using the modern system for setting up parser hooks on first parser initialization, instead of forcing the parser to load early just to register hooks.
I propose that we adopt a practice of amending old releases with new interfaces, essentially moving the burden from extensions to the core code itself. This doesn't mean that the whole new code needs to be backported. Take the RequestContext interface for example. We could very well add methods of this kind to our classes in 1.17: public function getUser() { global $wgUser; return $wgUser; }
IMO this is not a good idea; adding interfaces to an old version greatly increases the possibility of introducing errors to the old version, and creates more variability between sub-versions of a stable release branch. Some interface changes are also very complex -- "just adding" a few functions for RequestContext sounds like a sure recipe for getting something wrong. :)
"This works in 1.18 and later" is easier to understand than "This works in 1.18 and later, and also 1.17 but only 1.17.6 and later, and it still might not work because that 1.17 stub code may or may not actually work how you think it does from using the interface on 1.18".
Another idea is adding @since annotations to new methods and classes
and other changes. It's not fun to check the history of every function and determine the date it was added, just to make sure you don't accidentally introduce breakage when someone installs your extension in an older MediaWiki. Right now, the practice of adding @since annotations is not consistently followed or enforced.
Generally helpful, but note that @since alone doesn't always help as function signatures, accepted parameters, return values, side effects, etc also sometimes change over time. Ideally any kind of behavior change should be documented in the doc comments though, yes!!
As far as accidentally introducing breakages -- don't forget to actively *test* your extension with every version of MediaWiki that you say you support. Even without explicit interface changes there may be changed behavior or assumptions that you might forget at some point, and failing to test means you won't discover the problems until it's gone out into someone's hands.
Be sure to automate testing as much as possible, as humans are notoriously bad at remembering to do things regularly that are mildly inconvenient. :)
-- brion