On Mon, May 6, 2013 at 10:09 PM, Krinkle krinklemail@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".
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.
- 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.