On May 2, 2013, at 7:41 PM, Brad Jorsch <bjorsch(a)wikimedia.org> wrote: Fair point. We could use some other detectable way instead. However I'd prefer to keep things simple where "bug 123" is a mention and "Bug: 123" a resolution. Both are linkified by Gerrit, so that's not an issue. We could introduce something like "Bug-Fixed: 123". But I'm not sure if more syntax is the answer here. Note we also have people using "(bug 123)" in the subject still, and even people copying BugZilla's format of "Bug 123: title". Or we could simply omit this detection altogether and build the list from Bugzillla instead (resolved bugs marked as fixed for the appropriate milestone). Then we'd only have to make sure periodically that recently closed bugs without a milestone set get a milestone set. I believe several people perform such query already and fill in the missing milestones. No, the commit subject character limit is there for a good reason. We shouldn't change that for this. 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. 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. There are cases where it is important to write more elaborate notes for maintenance for extension developers and migration/upgrading for site administrators. And yes when the release notes are processed on the wiki page, things that need further documentation can be freely written in (for example) an "Upgrade" or "To extension maintainers" section – instead of scattered through the bullet point lists. For example: "If you don't know what you're doing, don't do it?" I think we can reasonably assume good faith that people won't go and mislabel things on the wiki page as "breaking" for a component they are not knowledgeable in. Plus, it is a wiki page, so it'll be a lot easier to keep track of and fix for everyone involved. This will make that easier since this would basically turn to doing a "post-merge" review of activities to some degree. -- Krinkle

On May 3, 2013, at 9:33 PM, Anomie wrote: 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. 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

On 7 May 2013 08:52, Brad Jorsch &lt;bjorsch(a)wikimedia.org&gt; wrote: I think you're missing the bit of Timo's proposal where all breaking changes have to *additionally* have a "Breaking change: Foo bar baz" in the "Breaking changes" section of the release notes, like they do already. ​​ Well, they're currently<https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf10#Breaking_c… documented<https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf11#Breaking_… within<https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf12#Breaking_chan… the <https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf1#Breaking_changes> release<https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf2#Breaking_chan… process<https://www.mediawiki.org/wiki/MediaWiki_1.22/wmf3#Breaking_chan…es>. I don't think Timo's suggesting changing this part of the process at all, just dumping the attempts to have the RELEASE-NOTES-1.XX file​ written through commits (which is often full of fail and people too often forget) and replacing it with commit logs. It doesn't remove the obligation on people making breaking changes to note this in the top-level notes. And this brings me back to my concern that others will incorrectly Yes, what constitutes a breaking change is in the eye of the beholder, but that's a distinct argument that we clearly have an operating definition for, because, umm, people are writing or not writing such notes right now. :-) ​J. -- James D. Forrester Product Manager, VisualEditor Wikimedia Foundation, Inc. jforrester(a)wikimedia.org | @jdforrester

On Tue, 07 May 2013 20:51:07 +0200, Krinkle &lt;krinklemail(a)gmail.com&gt; wrote: So in other words, this puts more burden on reviewers, making it harder to get changes merged, especially for new users? Because that's what this sounds like. Changes are already rotting in gerrit for a year (see the recent watchlist thread), and this certainly will not help. The current process for release notes is fine; we just need someone to write a custom merge driver for JGit to avoid the merge conflicts. This is a technical issue, not a policy one. -- Matma Rex

On Tue, 07 May 2013 21:00:05 +0200, Chad &lt;innocentkiller(a)gmail.com&gt; wrote: How catastrophic could turning it on be? Because if not very much, then this would greatly improve everyone's workflows. Just count the manual rebase patchsets on anything involving release notes... -- Matma Rex

On May 7, 2013, at 8:56 PM, Bartosz Dziewoński &lt;matma.rex(a)gmail.com&gt; wrote: How does this make anything harder for new users? If anything, it makes it easier by not having to worry about which file to edit, what to put in it etc. As for more burden on reviewers, I disagree. It might inspire them to give more care to proper commit subjects (and edit them liberally as needed) because if you leave it in bad shape, it needs to be fixed later in the notes. And here again, it simplifies things by maintaining release notes centrally and away from inside the tight development loop. Some of the same people will be doing both, but in the right frame of mind, instead of when you don't want to. The current process for release notes is not fine. It hasn't been fine for at least 2 or 3 releases. It is missing a lot, and what's there is (imho) poor quality (my own notes included). Improving that doesn't require moving the process, but I think this is an opportunity to fix a mess the right way at once. -- Krinkle