Hey,

1. start enforcing @since annotations for new core code

This would help so much :) I requested this about half a year back and got a bunch of sarcasm back then. Quite often I find out that I released some version of some extension that's not compatible with an older version of MediaWiki it's supposed to be compatible with, since I used a newly introduced method without realizing it. Then I need to find out where this is used, what version of MW it was introduced in (lot's of fun this step), add the @since annotation to core, update all extensions that are using this while they can't with b/c code, and make new releases for all these extensions. That's a lot of work, so I don't think it's to much to ask to add an @since tag to everything you add, how silly it might look (to you).

Cheers

-- Jeroen De Dauw http://www.bn2vs.com Don't panic. Don't be evil. --

"Niklas Laxström" niklas.laxstrom@gmail.com wrote in message news:CAAVd=jbYKaqR83tbwHAOiFiqrb_wcF70Jk=zdLqTWfiUMJn1_A@mail.gmail.com...

I would like for us to:

1. start enforcing @since annotations for new core code
2. encourage adding FC interfaces to previous branches where possible

(and to also make releases out of those branches including the interfaces)

I'm all in favour of requiring higher standards for documentation and annotations, as long as they are enforced consistently and everyone, however experienced, gets the same level of amiable prodding to conform to them. I'm also a fan of backporting interfaces as far as possible (I've broken a number of 1.19 commits into two bits and marked one of them for backporting to 1.18, for instance); but I wouldn't go so far as to say we should be adding features to released versions. I think we have enough of a workload with controlling one active release branch, and that trying to manage a second would merely distract us from the business of actually implementing these new features in the first place.

--HM

On Sat, Sep 3, 2011 at 12:40 AM, Niklas Laxström niklas.laxstrom@gmail.com wrote:

We are relatively strict keeping our new core code backwards compatible (BC). That compatibility does not come free, but who is it for?

Well it sort of does come free, just most people don't seem to use it.

We already have "/tags/RELX_YY_Z/extensions" (and "/tags/extensions" if they don't follow release numbering schemes (Example here are the Semantic* exts)) as well as "/branches/RELX_YY/extensions" where developers can keep extensions in a state to support BC with that version whilst integrating new features, One example of a dev doing this is the one working on the Favourites extension.

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:

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