[17:12:14] 19:08:47 - Base: https://wikimediafoundation.org/w/index.php?title=File%3AWikivoyage-logo.svg&diff=100188&oldid=93501 where do they recruit them? instead of deleting rubbish page they add an unneded templates there *facepalms*
[17:12:14] from -stewards. Can someone clean the speedy (in the wmf: it's rather slowy actually) category?
[21:01:05] #startmeeting RFC meeting
[21:01:05] Meeting started Wed Dec 17 21:01:05 2014 UTC and is due to finish in 60 minutes. The chair is TimStarling. Information about MeetBot at http://wiki.debian.org/MeetBot.
[21:01:05] Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
[21:01:05] The meeting name has been set to 'rfc_meeting'
[21:01:12] #chair DanielK_WMDE_
[21:01:12] Current chairs: DanielK_WMDE_ TimStarling
[21:01:22] hey, a new command :P
[21:01:25] #chair mark
[21:01:25] Current chairs: DanielK_WMDE_ TimStarling mark
[21:01:41] does being a chair give me magic powers?
[21:02:03] #topic Release notes automation | RFC meeting | PLEASE SCHEDULE YOUR OFFICE HOURS: https://meta.wikimedia.org/wiki/IRC_office_hours | Please note: Channel is logged and publicly posted (DO NOT REMOVE THIS NOTE) | Logs: http://bots.wmflabs.org/~wm-bot/logs/%23wikimedia-office/
[21:02:17] #link https://www.mediawiki.org/wiki/Requests_for_comment/Release_notes_automation
[21:02:26] o/
[21:03:27] ok, I've got to go now, sorry everyone
[21:03:41] Daniel is frantically reading the meetbot manual
[21:03:53] he will run the rest of the meeting
[21:04:20] thanks Tim-away
[21:04:26] * aude waves
[21:04:41] so, is Krinkle with us?
[21:04:50] Krinkle, do you want to present the RFC?
[21:05:55] hm... he was a round a few minutes ago.
[21:06:30] so, the basic idea is to automatically generate release notes from commit messages
[21:06:48] one question is the format - how do we put release notes into the commit messages?
[21:07:12] another question is the automatization - when and how do release notes get updated?
[21:07:23] any thoughts and ideas?...
[21:07:29] looks reasonable to me at a glance
[21:07:29] * DanielK_WMDE_ goes to read the rfc more closely
[21:07:37] our release notes are kind of structured, so if in your commit message you have something like:
[21:07:42] * New configuration settings:
[21:07:54] ** $wgFooBar - controls foo and bar
[21:07:58] i imagine jenkins could do it (liek it generates code coverage daily)
[21:08:00] it should be easy for a script to read it
[21:08:07] jenkins can do any task
[21:08:09] :P
[21:08:17] RELEASE New features
[21:08:19] * Bullet point to add to the release notes
[21:08:20] that spans multiple lines.
[21:08:25] ^--- that's the format the RFC suggests
[21:08:54] I guess it'd be nice to have a jenkins "test" job to parse the commit summary and show what it would put it into the release notes as
[21:08:55] we already have a BUG keyword for bug fixes... should that be recycled?
[21:09:00] that seems a little verbose to me, but also works
[21:09:02] So, we can fix it whilst we stil can
[21:09:03] or shall we keep that separate?
[21:09:13] There are 2 fairly different options in the proposal. One is to add magic words to commit messages and parse them with some bot. The other is just to dump all commit messages into a wiki page and make somebody clean them up.
[21:09:13] Bug should be separate imo
[21:09:32] nobody is going to clean them up
[21:09:37] from a wiki page
[21:09:38] bd808: i think the "dump all" option is off the table. at least that was my understanding.
[21:09:39] lol
[21:09:50] * aude missed tha tpart
[21:09:56] (there's also the null proposal where we keep doing what we're doing now, but with fixed tooling)
[21:09:59] DanielK_WMDE_: I'm back.
[21:10:03] hey :)
[21:10:22] aude: I think someone is going to have to. Someone (or thing!) has to create the main [[MediaWiki 1.24]] landing pages which should be a summary of the release notes
[21:10:35] DanielK_WMDE_: I'm mostly for either putting it on a wiki page or in a file in the repo, and only updating as part of making a release.
[21:10:37] legoktm: hmm
[21:10:39] (that is, a proper merge driver, to avoid silly merge conflicts; that's the only pain point with the current system, afaik)
[21:10:44] Krinkle: so, we were just talking about "parse special keywords" vs. "dump all commit messages". Also, what about the BUG: keyword. and when and where does stuff go to the release notes
[21:11:00] not fancy, but there's also what reedy does to make a log of changes in each branch that is deployed
[21:11:09] I was about to mention that
[21:11:13] It's very basic
[21:11:15] +1 to MatmaRex
[21:11:29] make-deploy-notes
[21:11:33] https://www.mediawiki.org/wiki/MediaWiki_1.25/wmf10/Changelog
[21:11:56] DanielK_WMDE_: I don't think we should put anything special in the commit message like "Release note: ..". I'd like enforcing stricter review to avoid useless commit messages. A good commit message should be sufficient for the average change log entry. And then some additional instructions maybe for special things (like we do with the [[MediaWiki x.x]] pages already).
[21:12:02] Reedy, Krinkle: so are you in favor of collecting all commit messages? or only the bits that have special syntax/markers?
[21:12:12] Wasn't there a thread on one of the mailing lists where someone said they had a merge script that took care of most of the conflicts automatically?
[21:12:21] yes. i did, and i have.
[21:12:28] omfg
[21:12:35] MatmaRex for release note manager
[21:12:36] Krinkle: in my experience, there is a lot of stuff in commit messages that shouldn't go into the release notes.
[21:12:43] https://github.com/MatmaRex/mediawikireleasenotes-driver
[21:12:46] I've seen this adopted at git, jquery, npm, grunt, gulp and elsewhere and seems to be working well. And I tried it here for oojs and oojs-ui. release notes being reduced from changelog summaries, yeah.
[21:12:51] at least in the wikidata project, we use them extensively for internal coordination
[21:12:54] it can't be straight-up used with Gerrit since it reimplements Git in Java.
[21:13:27] DanielK_WMDE_: just the stuff marked with RELEASE: blah ....
[21:13:50] aude: i'd be in favor of that, but Krinkle disagrees if i'm understand it correctly
[21:13:51] trivial stuff wouldn't need to have that
[21:14:08] #info MatmaRex has a release notes merger that deals with most conflicts automatically
[21:14:21] DanielK_WMDE_: Before anything, we need to establish our intended purpose.
[21:14:38] I think the main problem right now is that our release notes are next to useless. I highly doubt who uses them.
[21:14:40] the purpose of release notes?
[21:14:45] And those that do, have different expectations.
[21:14:50] #link https://github.com/MatmaRex/mediawikireleasenotes-driver
[21:15:00] thanks!
[21:15:00] It's a subset of changes that resembles randomness
[21:15:06] Krinkle: i agree
[21:15:21] collecting *everything* would help with that. but everything is a *lot*
[21:15:31] the notes would be too huge to be useful
[21:15:43] "Fix typo in blah...."
[21:15:53] too much trivial if it collected everything
[21:16:05] DanielK_WMDE_: What I do in oojs and oojs-ui, and also see happening in most major libraries on github (including jquery, grunt, nodejs, npm, git/git and more) is to be strict in commit messages. And take the dump of that as starting point. Then the brancher/releaser is responsible for filtering that down.
[21:16:17] aude: Yes, but collecting doesn't mean including.
[21:16:21] It's trivial to filter it down.
[21:16:23] it would also include a bunch of changes that arn't relevant, like a message about a new feature, then 12 messages about fixing that new feature
[21:16:24] Krinkle: to me, the purpose of release notes is to document a) breaking changes b) new features
[21:16:28] And probably a lot better use of our time
[21:16:34] additions to the api, bug fixes, etc, are nice, but not that important
[21:16:49] and would mean the commit message is actually not uselessly generic or intenrally scoped to make no sense to another person not reading the rest of the message or diff.
[21:17:00] We did release notes based on tickets closed at $DAYJOB-1. The product owner and his tech writer started from that and made the public notes
[21:17:16] But since MW doesn't have a PO...
[21:17:19] #info Krinkle wants all commit messages in a big file, manually compiled into release notes by a release manager
[21:18:02] Krinkle: we (the wikidata team) are pushing for really small commits (i'm not very good at this). that means very high granularity on the notes.
[21:18:02] bd808: ... yet
[21:18:13] DanielK_WMDE_: Embracing component prefixes, capitalisation, and grammatic form also helps making things a lot easier to read.
[21:18:16] Krinkle: i think that high granularity is going to be a problem
[21:18:34] greg-g: Not holding my breath
[21:18:36] DanielK_WMDE_: I've seen it work in git, jquery, nodejs and npm. Those are big projects.
[21:18:40] Krinkle: do you want release notes for "removed outated documentation from 5 files"?
[21:18:49] we have a ton of that kind of commit messages
[21:19:02] DanielK_WMDE_: grep -v '^doc: '
[21:19:06] could be a very simple solution
[21:19:18] Or maybe we're just too sloppy with our commit messages in general, which we definitely are at this point.
[21:19:18] DanielK_WMDE_: See https://github.com/wikimedia/oojs-ui/blob/v0.4.0/History.md#v040--2014-12-05
[21:19:37] I see it as the responsibility of the reviewer/merger to enforce this.
[21:20:08] Krinkle: now i'm confused - you want a "doc" prefix?
[21:20:35] DanielK_WMDE_: No, not per se. I'm just saying, if you're worried about how much work it is to filter out "typo commit" and "add missing doc" and such, we can easily make groups for those
[21:20:37] and filter them out
[21:20:45] #info Daniel likes explicit markers like [BREAKING CHANGE] or BUG: T74531
[21:20:52] "This edit is minor"
[21:21:14] DanielK_WMDE_: Referencing tickets and identifying breaking changes should always be done indeed. I agree. Regardless of how we compile the notes.
[21:21:14] Can we add a minor edit checkbox to gerrit?
[21:21:25] Reedy: :)
[21:21:32] breaking change in subject line, ticket references in meta footer.
[21:21:33] https://github.com/wikimedia/oojs-ui/blob/HEAD/History.md is more significant, BTW.
[21:21:56] * James_F is the main release manager for OOjs UI, effectively.
[21:22:01] https://github.com/joyent/node/commits/v0.11.14
[21:22:03] Krinkle: so, maybe it's not really about writing the release notes into the commit message, but about using the headline of commit messages with specific markers
[21:22:08] It works well, but our scale isn't quite MediaWiki's. :-)
[21:22:14] DanielK_WMDE_: Agreed.
[21:22:31] DanielK_WMDE_: Yep, I meant commit subject, not commit message. dumping the entire message would be a lot of work indeed.
[21:22:51] If it doesn't fit in the commit subject, the commit needs work.
[21:23:16] Anyway, we can always edit manually, add extra text as we near a release as needed. This is about the 80%/99% stuff.
[21:23:25] #info Krinkle, James_F and Daniel agree that it should be only the commit subject (headline). And that we want keywords in the commit message for filtering.
[21:23:47] Krinkle: should the marker be in the subject too? I think not....
[21:24:08] DanielK_WMDE_: marker?
[21:24:08] the subject line is limited to what, 60 characters? it's fairly short already.
[21:24:10] breaking changes, yes. bug, no.
[21:24:13] 80-100
[21:24:15] Krinkle: stuff like "BREAKING"
[21:24:19] Yes, definitely.
[21:24:28] At least imho.
[21:24:28] :)
[21:24:40] Krinkle: no, wait - git tells me it's a lot less. let me check.
[21:25:00] probably 62 according to some rules
[21:25:13] but you can't write a good summar yf anything in 62 characters
[21:25:17] so we cheat and use 100
[21:25:23] 62 for the body,
[21:25:24] of*
[21:25:26] 50 for the subject
[21:25:30] according to vim.
[21:25:39] yeah, much less that.
[21:25:45] There's no hard limit, there never was. Just look at our history and that of the projects I mentioned before.
[21:25:56] including git-core itself.
[21:26:08] Around 60 characters should be plenty.
[21:26:17] Krinkle: so you are saying we should write longer subject lines?
[21:26:27] short subjects make good mail subjects
[21:26:27] i'm not sure why we skipped over to keeping the release notes in commit messages immediately. adding them to a file neatly avoid this issue.
[21:26:29] Not longer than 80-100 I'd ssay.
[21:26:33] (i think that's the main reason for the low limit)
[21:26:37] Yeah
[21:26:42] Krinkle: that's twice the current convention
[21:26:44] well also just in general. It needs to be readable/scannable.
[21:26:49] DanielK_WMDE_: tehre is no current convention.
[21:26:56] There's a page I wrote on mw.org, but nobody is enforcing it in code review.
[21:27:07] vim is nagging me if i got longer :)
[21:27:12] twice the Git's convention* but indeed nobody around here tried to enforce it.
[21:27:12] Other than a few odd balls, including myself.
[21:27:20] DanielK_WMDE_: that's git doing that for you.
[21:27:28] And git doesn't even use that themselves.
[21:27:35] and can be configured differently
[21:27:36] anyway
[21:27:38] [22:26] i'm not sure why we skipped over to keeping the release notes in commit messages immediately. adding them to a file neatly avoid this issue.
[21:27:53] as well as the issue of deciding what format to use
[21:28:40] we have a perfectly good process (i deem it 'perfectly good' since i saw no one point out any issues with it, other than the technical one of merge conflicts)
[21:28:40] MatmaRex: What do you mean by "format"?
[21:28:43] #info Krinkle proposes to have commit subject lines up to 80 or 100 characters
[21:28:58] James_F: i mean the five screens of bikeshedding on the proposal page, and the half-hour of bikeshedding here. :)
[21:29:05] MatmaRex: in my experience, the current process leads to merge conflicts, but worse, it leads to a lot of omissions-
[21:29:07] (i may have exaggerated slightly.)
[21:29:20] a lot of times, folks just forget to add things to the release files
[21:29:21] DanielK_WMDE_: people omit stuff because they don't want to deal with the merge conflicts.
[21:29:34] DanielK_WMDE_: merge conflicts are easy to avoid with some goodwill, and yes, what legoktm said
[21:29:35] also because they simple forget or don't care
[21:29:37] .. and because it's not clear what' worthy of including
[21:29:38] Agreed with legoktm.
[21:29:49] either that, or just because they don't care - and this won't change if we make the put in the notes differently
[21:29:54] and a patch contributor shouldn't need to know either.
[21:29:55] they will continue not putting in any
[21:29:55] Lots of follow-up commits adding release notes for something once they're merged.
[21:30:00] DanielK_WMDE_: If someone doesn't include release notes, and it should have them, it's up to reviewers to -1 (or not +2) for them
[21:30:09] using commit subjects won't help either, since they'll continue not caring about their commit messages.
[21:30:15] I actively avoid adding things to the release notes because of merge conflicts
[21:30:22] legoktm: we need better conventions about what should go into the release notes
[21:30:29] ^ true
[21:30:41] agreed
[21:30:44] #MatmaRex favors manualy maintained release notes, with better conflic resolution
[21:30:48] err
[21:30:49] That would be a great place to start. Why do we make them and for whom?
[21:30:51] #info MatmaRex favors manualy maintained release notes, with better conflic resolution
[21:31:01] git documents theirs quite well: https://github.com/git/git/blob/v1.9.0/Documentation/SubmittingPatches#L87
[21:31:28] jquery doesn't document it as explicit, but not bad either: http://contribute.jquery.org/commits-and-pull-requests/#commit-guidelines
[21:31:28] #info if we keep the manual system, we need better conventions on what changes need release notes.
[21:31:28] my proposal is to install the merge driver on some repo somewhere that jenkins can access, and then make jenkins run `git review -d NNN && git rebase master && git review -f` if the change is unmergeable
[21:32:17] Also note that we'd have to duplicate this process for all our repos. And they're a growing number. I'd like the same process to apply to e.g. wikimedia/cdb
[21:32:23] bd808: For sysadmins who are upgrading and need to know what config settings changed, and where they should be expecting errors (this entire code section was refactored, so it might have regressions) and extension developers who need to know what has changed to make their extension compatible
[21:32:37] #info conflict resolution could be managed by jenkins
[21:32:44] #link http://contribute.jquery.org/commits-and-pull-requests/#commit-guidelines
[21:32:51] #link https://github.com/git/git/blob/v1.9.0/Documentation/SubmittingPatches#L87
[21:33:10] aggregating them, filtering and prepending to a History.md file at release time would be nice. The commit could be in gerrit for a few days for people to add anything that should be in there (e.g. like now, the extra blurp about setting up Composer)
[21:33:22] (i don't think we keep any release notes in most repositories, the only ones i know where we do are mw/core and oojs repos)
[21:33:28] Krinkle: Right now we don't really do release notes for the rest of our repos.
[21:33:33] Krinkle: Do you think that should change?
[21:33:36] (there are probablysome tasks and rfcs about that)
[21:33:44] so, can we make a list of things that need release notes? breaking changes, new config settings, new hooks, new api modules...
[21:33:45] James_F: Yep, which is a problem imho. Makes it untransparent what's going on.
[21:33:51] https://www.mediawiki.org/wiki/VisualEditor/status notwithstanding.
[21:33:52] Especially for things published to composer.
[21:34:36] #info we currently don't have release notes for most components other than core. this should probably change
[21:34:54] i'm a big fan of putting all the info into commit messages, really.
[21:35:04] i write them at the right moment to think about release notes
[21:35:15] Yeah
[21:35:17] and it ties i nvery well with the BUG: keyword, and marking things as BREAKING
[21:35:34] manual additions to the notes are still possible of course
[21:35:45] hm...
[21:36:10] if we start including all commit subjects per default, that's going to be a lot. And we need a way to put them into sections (keywords?)
[21:36:23] maybe such keywords could also decide if the commit goes into the release notes at all
[21:36:30] if so, we could easdily accomodate bpoth styles
[21:36:47] some people edit the notes file, others put a RELEASENOTE marker into commit message
[21:36:55] would that be a viable compromize?
[21:37:01] I think we should just standarize on one...
[21:37:30] Well, I think it's not a compromise to say that additional information about a feature or major change can be added manually at release time. That seems fair.
[21:37:47] personally i don't care very much what we do, but i'd prefer if we did only one thing. i'm advocating the simplest solution, just fixing what we already use.
[21:37:48] It's like writing the announcement e-mail or creating [[MediaWiki x.x]], that's custom content.
[21:37:53] Krinkle: i was thinking "at any time".
[21:38:07] DanielK_WMDE_: What would this RELEASENOTE marker be like?
[21:38:23] DanielK_WMDE_: Hm.. interesting. Where would they do that?
[21:38:31] Would we have a bot appending commit subjects to a file continuously?
[21:38:32] Krinkle: in the release notes file?
[21:38:57] Krinkle: the markers would be things like BUG, BREAKING, or just RELEASENOTES. Could also be NEW XXX.
[21:39:39] Krinkle: could be, but why is that needed? when composing the final notes, you take the commit messages, and the manually maintained file, and ocmbine them
[21:39:47] Hm.. the markers I was referring to would refer to a component, not a type of commit.
[21:40:10] I think trying to prefix the type will get messy.
[21:40:25] #info legoktm and MatmaRex prefer to only have people maintain the notes manually OR use commit messages, not both. Daniel wants to leave it to individual comitters.
[21:41:03] Krinkle: the components should actually be separate repos with separate release notes :) some day...
[21:41:44] I'd vote for using only commit subjects for regular entries. And any elaborate documentation (should be edge case, 0 or 1, 2 per release) can be added wherever/whenever depending on how we end up on this RFC. Shouldn't drive the RFC direction imho.
[21:41:53] DanielK_WMDE_: No, I disagree.
[21:41:58] Krinkle: why would that get messy? also, i think they could be anywhere in the message
[21:41:58] DanielK_WMDE_: Every project has components.
[21:41:59] DanielK_WMDE_: YOu are a crazy dreamer. I like that. :)
[21:42:19] DanielK_WMDE_: Sure things should be split at a higher level, but there will still be components. Every project has them.
[21:42:33] bd808: imagine all the coders, rebasing in harmony...
[21:43:20] Krinkle: yes. down to files and methods. but keeping that organized seems messy
[21:43:36] i'd basically use markers to indicate the section i nthe release notes.
[21:43:42] whatever these sections would be
[21:43:50] DanielK_WMDE_: Breaking is not a section, it's a flag.
[21:44:04]