On 7 May 2013 08:52, Brad Jorsch bjorsch@wikimedia.org wrote:
Oh, so not mentioning the breaking API change at all? Definitely not good.
I think you're missing the bit of Timo's proposal where all breaking changes have to *additionally* have a "Breaking change: Foo bar baz" in the "Breaking changes" section of the release notes, like they do already.
How do these "extra" notes get noted wherever you intend for them to be noted? That seems to be missing from the proposal.
Well, they're currentlyhttps://www.mediawiki.org/wiki/MediaWiki_1.21/wmf10#Breaking_changes documentedhttps://www.mediawiki.org/wiki/MediaWiki_1.21/wmf11#Breaking_changes withinhttps://www.mediawiki.org/wiki/MediaWiki_1.21/wmf12#Breaking_changes the https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf1#Breaking_changes releasehttps://www.mediawiki.org/wiki/MediaWiki_1.22/wmf2#Breaking_changes processhttps://www.mediawiki.org/wiki/MediaWiki_1.22/wmf3#Breaking_changes. I don't think Timo's suggesting changing this part of the process at all, just dumping the attempts to have the RELEASE-NOTES-1.XX file written through commits (which is often full of fail and people too often forget) and replacing it with commit logs. It doesn't remove the obligation on people making breaking changes to note this in the top-level notes.
And this brings me back to my concern that others will incorrectly
think they know what is considered a "breaking" change in the API.
Yes, what constitutes a breaking change is in the eye of the beholder, but that's a distinct argument that we clearly have an operating definition for, because, umm, people are writing or not writing such notes right now. :-)
J.