On May 3, 2013, at 9:33 PM, Anomie wrote: > On Fri, May 3, 2013 at 1:02 PM, Krinkle wrote: >> First of all, I think a lot of our commit subjects are poorly written, >> even for a commit message. Having said that, a good commit subject is >> also a good release note (that is, if the change itself is notable for >> release notes). I don't think that these extensive paragraphs of text >> we are known for in release notes are a good habit. > > In my opinion, a good commit summary and a good release note are not > necessarily the same thing at all, otherwise we could just dump the > git log as the release notes and be done with it. Release notes > *should* go into sufficient detail to tell the reader what it is they > should be noting. >
I believe that a (filtered) list of good summaries is indeed sufficient for the release notes. The projects I referenced as example already proof this fact. I don't think it is realistic to think that we need a different type of message for the release notes for each change. There are some changes (by far not the majority) that require special attention, for example when: * the site admin needs to make changes to their configuration prior or during upgrading * the site admin needs to update specific extensions at the same time due to breaking compatibility * an extension maintainer should make changes soon due to deprecation of a feature * an extension maintainer needs to ensure changes are made due to removal of a feature * etc. However in such case an entry in the list of changes in the release notes that is more elaborate than the others doesn't really stand out. In such case, as I believe we have in most cases already, the text in question needs to be written in a paragraph in the Compatibility, Upgrading or similar sections. >> We already have a 62-char limit for the commit subject. That seems to >> be going well. Assuming that we properly summarise changes that way >> already, why would one need more room in the release notes? It is the >> same event. > > 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" Regarding the change itself: 1) I think this hook should be renamed as it ambiguous. It could be a hook for changing langlinks when parsing/saving a page (input) or a hook to implement a custom source of langlinks when requesting them (output). 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. Regarding the release notes: 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. Which brings me to another point. No doubt these are breaking changes, but in a way almost every change is potentially a breaking change for something for someone, somewhere. The kind of changes that break things we previously supported should be noted in those separate sections. Thus resulting in a situation where the change log is skimmable for the curious and only containing summaries of notable changes. And anything that requires attention is clearly separate and to be read first for all eyes (breaking changes for site admins or extension maintainers and configuration changes). -- Krinkle _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
