On 7 May 2013 08:52, Brad Jorsch <bjorsch(a)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
currently<https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf10#Breaking_c…
documented<https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf11#Breaking_…
within<https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf12#Breaking_chan…
the <https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf1#Breaking_changes>
release<https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf2#Breaking_chan…
process<https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf3#Breaking_chan…es>.
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.
--
James D. Forrester
Product Manager, VisualEditor
Wikimedia Foundation, Inc.
jforrester(a)wikimedia.org | @jdforrester