On May 7, 2013, at 5:52 PM, Brad Jorsch <[email protected]> wrote:
> On Mon, May 6, 2013 at 10:09 PM, Krinkle <[email protected]> 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 _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
