On Mon, May 6, 2013 at 10:09 PM, Krinkle <krinklemail(a)gmail.com> wrote:
On May 3, 2013, at 9:33 PM, Anomie wrote:
Taking a recent example[1], please tell me how to
compress the
following into 62 characters:
(in the New features section)
* (bug 45535) introduced the new 'LanguageLinks' hook for manipulating the
language links associated with a page before display.
(in the API section)
* BREAKING CHANGE: action=parse no longer returns all langlinks for the page
with prop=langlinks by default. The new effectivelanglinks parameter will
request that the LanguageLinks hook be called to determine the effective
language links.
* BREAKING CHANGE: list=allpages, list=langbacklinks, and prop=langlinks do not
apply the new LanguageLinks hook, and thus only consider language links
stored in the database.
I don't think "Add LanguageLinks hook with breaking changes to 4 API
modules" is detailed enough for release notes. And before you try to
cheat and split it into multiple commits, note that the new hook and
what it means for how langlinks are stored in the database is what is
the breaking change in those API modules; the actual changes to the
API modules are just mitigating or noting it.
The summary actually used for that revision, BTW, was "(bug 45535)
Hook for changing language links".
[1]:
https://gerrit.wikimedia.org/r/#/c/59997/
Though this is not a typical type of change and I think you already
know the answer, I'll give you my take on this one.
As commit subject (and thus release notes change log entry) I'd use:
"Add hook LanguageLinks for changing langlinks before display"
Oh, so not mentioning the breaking API change at all? Definitely not good.
2) I'm not sure why you'd make ApiParse not
call the hook by default.
An option to get the raw langlinks may be useful (I'd be curious as to
the use cases, but I can imagine), but doing so by default seems odd.
I suggested that too. The Wikidata people disagreed, and I didn't feel
like arguing over it.
This change is a typical case where extra-awareness
notes are in
order. I personally wouldn't consider these breaking changes, but
anyway, they are certainly important. So these are are the kind of
changes for which you'd include notes in a separate section.
How do these "extra" notes get noted wherever you intend for them to
be noted? That seems to be missing from the proposal.
And this brings me back to my concern that others will incorrectly
think they know what is considered a "breaking" change in the API.
--
Brad Jorsch
Software Engineer
Wikimedia Foundation