On May 2, 2013, at 7:41 PM, Brad Jorsch bjorsch@wikimedia.org wrote:
I like the idea of not having to mess with RELEASE-NOTES-#.## merge conflicts. But I'm not entirely sure about everything in the proposal.
On Thu, May 2, 2013 at 12:30 PM, Krinkle krinklemail@gmail.com wrote:
For more details see Proposal 2 on this page:
https://www.mediawiki.org/wiki/Requests_for_comment/Release_notes_automation...
To avoid wrong entries for bugs that were merely mentioned in the commit message but not fixed in that commit, it becomes more important that we enforce a consistent format. "bug 123" is a mention. "Bug: 123" in footer meta-data indicates the bug was fixed.
So we're changing the semantics of that "Bug" footer already? Instead of being used for searching changesets related to a bug, now it's only for searching changesets actually fixing a bug? And what about changesets that only partially fix a bug? Or bugs where changes to both core and extensions are needed to fix a bug?
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.
We can't use the commit message subject because they aren't always the same as what you want to write in the release notes.
So are we getting rid of the recommended less-than-50-character limit on commit subjects? Or are we assuming that whoever volunteers to clean up the subject-dump will expand on it as necessary?
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:
== Changes ==
- foo: Upgrade to version 1.20
- bar: Don't silently ignore invalid values in event handler
- ..
== To extension maintainers ==
Various bar plugins are known to call the event handler with an object instead of an array containing the object. This was previously silently skipped. This failure is now explicit by throwing an invalid arguments exception.
Mark entries with the relevant labels ("New", "Removed", "Breaking" etc.)
I worry that whoever is doing this for API changes (if it doesn't wind up being me) won't know how we determine "Breaking" for API changes. I.e. "anything that's not backwards-compatible for API users".
"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