On Fri, Sep 2, 2011 at 7:40 AM, Niklas Laxström
<niklas.laxstrom(a)gmail.com>wrote;wrote:
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:
1) keep the old interface available unless it makes no sense anymore
2) 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