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.
Extra notes are added like usual, except now on the release notes wiki
page instead of the file in version control.
Now I hear you thinking, does that mean every patch contributor now
needs to know about this wiki page and wait for the change to be
approved and then edit the page to add notes? No.
It is the duty of repository co-owners to make wise decisions beyond
just code quality. About what changes go in what release (if at all),
whether the introduced features are in the best interest of the users
and that we can maintain them and are willing to support them. And to
be aware of whether a change is breaking or not, and if so if whether
the change should still go in the current release or a the next (e.g.
don't remove/break without deprecation first, if possible).
As such the co-owners of a repository (not per se the patch
contributor) will know these things and should take care (or delegate)
the addition of proper release notes as you deem appropriate for the
users of the component(s) you maintain.
This also means that there's no uncomfortable waiting time between
submission and (if needed for this particular change) the editing of
the wiki page. Because can write them right after you approve a change
(or do it later).
-- Krinkle