Summary of IRC Meeting in #aurora at Mon May 11 18:01:25 2015: Attendees: thalin, davmclau, marti_, jfarrell, jcohen, wfarner, Yasumoto, kts, mkhutornenko, zmanji, dlester, dlester_
- Preface - 0.8.0-RC1 - Markdown documentation - Action: kts to start discussion on documentation automation on dev@ - GSOC 2015 IRC log follows: ## Preface ## [Mon May 11 18:01:43 2015] <marti_>: ok :D [Mon May 11 18:01:57 2015] <wfarner>: welcome, everyone. if you're joining us for the first time - everyone is welcome to participate! [Mon May 11 18:02:03 2015] <wfarner>: let's start with the roll call [Mon May 11 18:02:03 2015] <wfarner>: here [Mon May 11 18:02:08 2015] <thalin>: here [Mon May 11 18:02:10 2015] <jcohen>: ahoy ahoy [Mon May 11 18:02:11 2015] <mkhutornenko>: here [Mon May 11 18:02:24 2015] <marti_>: here [Mon May 11 18:02:26 2015] <jfarrell>: here [Mon May 11 18:02:27 2015] <Yasumoto>: howdy [Mon May 11 18:02:44 2015] <zmanji>: here [Mon May 11 18:03:50 2015] <dlester>: here ## 0.8.0-RC1 ## [Mon May 11 18:04:51 2015] <jfarrell>: rc1 vote thread is at http://s.apache.org/3bN [Mon May 11 18:05:00 2015] <wfarner>: w are at 4 binding, 1 non-binding votes [Mon May 11 18:05:04 2015] <wfarner>: s/w/we/ [Mon May 11 18:05:22 2015] <wfarner>: if you haven't already voted, please do so! [Mon May 11 18:05:25 2015] <jfarrell>: have left the vote open since it was started on a friday, wanted to make sure people where aware of it, plan on closing it later tonight [Mon May 11 18:05:40 2015] <wfarner>: jfarrell: sounds great, thanks! [Mon May 11 18:06:28 2015] <wfarner>: jfarrell: there was a chat in here last week about more human-friendly release notes. do you have any thoughts on where that would/should go? [Mon May 11 18:06:38 2015] <wfarner>: should we do that in JIRA? [Mon May 11 18:07:06 2015] <kts>: here [Mon May 11 18:07:23 2015] <wfarner>: dlester: ^^ in case you have thoughts [Mon May 11 18:07:31 2015] <jfarrell>: we should move that discussion to the dev@ list [Mon May 11 18:08:17 2015] <wfarner>: sure thing, happy to do that. just for for my edification - what's the common practice you've observed in ASF? [Mon May 11 18:08:23 2015] <dlester>: human-friendly release notes would be great, and would probably make writing release blog posts easier [Mon May 11 18:08:55 2015] <jfarrell>: cassandra hand edits the CHANGELOG as they go, per commit [Mon May 11 18:09:17 2015] <jfarrell>: jira automatically gives up this https://issues.apache.org/jira/browse/aurora/?selectedTab=com.atlassian.jira.jira-projects-plugin:changelog-panel [Mon May 11 18:09:41 2015] <jfarrell>: so finding a good solution somewhere inbetween so we dont have to hand edit on each commit, but are not fully relying on jira filters [Mon May 11 18:10:12 2015] <wfarner>: sounds good. i'll open the dev@ discussion today [Mon May 11 18:10:38 2015] <dlester>: Mesos has a section its change-log that's human-redable and helpful IMO https://github.com/apache/mesos/blob/master/CHANGELOG [Mon May 11 18:10:55 2015] <jfarrell>: perhaps a handedited NEWS section that details things like upgrades [Mon May 11 18:11:06 2015] <jfarrell>: and we leave the changelog as the automated process [Mon May 11 18:11:43 2015] <jfarrell>: like this: https://github.com/apache/cassandra/blob/trunk/NEWS.txt [Mon May 11 18:11:44 2015] <wfarner>: one thing i pitched out was an RCS-style tag in the CHANGELOG where the release script would insert tickets for $RELEASE_NEXT [Mon May 11 18:11:52 2015] <jcohen>: Iâm fine with an automated changelog, but I think thereâs definitely benefits to a hand curated news section as well. [Mon May 11 18:12:08 2015] <wfarner>: yeah, i think both are really valuable [Mon May 11 18:12:18 2015] <jcohen>: things like the security work are impossible to pick out from the changelog for 0.8.0 [Mon May 11 18:12:44 2015] <wfarner>: anything else on this topic? [Mon May 11 18:13:07 2015] <jfarrell>: rest can go to dev@ ## Markdown documentation ## [Mon May 11 18:14:16 2015] <wfarner>: context: we have a script that handles publishing docs on aurora.apache.org (thanks dlester!) that renders our markdown docs [Mon May 11 18:14:35 2015] <wfarner>: trouble is that it doesn't have perfect consistency with github's renderer [Mon May 11 18:14:51 2015] <wfarner>: leading to issues like: [Mon May 11 18:14:51 2015] <wfarner>: AURORA-870 [Mon May 11 18:14:57 2015] <wfarner>: AURORA-1314 [Mon May 11 18:15:06 2015] <jfarrell>: we are using middleman to handle the conversion [Mon May 11 18:15:34 2015] <jfarrell>: redcarpet is the underlying renderer [Mon May 11 18:15:52 2015] <wfarner>: as a tactical fix, i would like to propose that we explore github's rendering API for better consistency: https://developer.github.com/v3/markdown/ [Mon May 11 18:16:25 2015] <kts>: should we publish documentation to our site at all? it's currently a manual process and usually out of date [Mon May 11 18:16:37 2015] <wfarner>: emphasis tactical [Mon May 11 18:17:02 2015] <wfarner>: though if we do go that route, it would make the tactical work throwaway [Mon May 11 18:17:04 2015] <davmclau>: +1 for not duplicating documentation [Mon May 11 18:17:17 2015] <dlester>: I strongly think we should keep the documentation on the site, because it drives traffic and interest in the project / website [Mon May 11 18:17:20 2015] <jfarrell>: thoughts on using the new gh-pages branch route offered? [Mon May 11 18:17:20 2015] <kts>: I'm okay with github being the source-of-truth for now (well it's also in the source dist for releases which is the real source-of-truth) [Mon May 11 18:17:36 2015] <davmclau>: We could just have the documentation link on the site point to github, no? [Mon May 11 18:18:20 2015] <kts>: dlester: if we do that we need automation to ensure it's not out-of-date and need to be able to (for example) link to code [Mon May 11 18:18:35 2015] <jfarrell>: ping dnorris ^^ [Mon May 11 18:19:18 2015] <wfarner>: oh, speaking of gh-pages...is the git-based site a thing now? [Mon May 11 18:19:21 2015] <jfarrell>: we might just be issing the plugin config, looking at middleman-syntax looks like its an option [Mon May 11 18:19:27 2015] <dlester>: worth noting the issues that are identified here are problems that the Mesos similarly experiences b/c there's a similar workflow [Mon May 11 18:19:32 2015] <dlester>: fix it once, works for both projects [Mon May 11 18:19:33 2015] <jfarrell>: wfarner: yes [Mon May 11 18:20:27 2015] <wfarner>: jfarrell: where can i learn how to use it? [Mon May 11 18:21:19 2015] <jfarrell>: right now there is only a blog post about it with minimal info, other than that just the scripts that make it possible [Mon May 11 18:21:28 2015] <dlester>: I agree with kts, automating the generation of these pages would be really helpful [Mon May 11 18:21:45 2015] <jfarrell>: wont work out of the box with our setup, but could be tailored to meet our needs [Mon May 11 18:21:51 2015] <kts>: also I'd like to move to a model where pages like http://aurora.apache.org/documentation/latest/configuration-reference can be generated from pydoc [Mon May 11 18:27:02 2015] <dlester>: it also seems like a reasonable expectation for committers to run `rake` and `svn commit` whenever they add commit documentation to the website, everyone has access [Mon May 11 18:27:02 2015] <kts>: there's really no reason we should be manually retyping fields into a markdown doc [Mon May 11 18:27:02 2015] <wfarner>: kts: one giant leap at a time :-) [Mon May 11 18:27:02 2015] <kts>: wfarner: agree, just trying to make sure whatever evolutionary step we take gets us closer to that goal [Mon May 11 18:27:02 2015] <kts>: Thrift API docs and javadocs should be publishable/published as well [Mon May 11 18:27:02 2015] <dlester>: kts: that's easy to add a rake task with the current workflow [Mon May 11 18:27:02 2015] <kts>: no point writing them if noone can find them [Mon May 11 18:27:02 2015] <wfarner>: so...what's the action to take here? [Mon May 11 18:27:02 2015] <wfarner>: 1. educate everyone on updating the site via git [Mon May 11 18:27:02 2015] <jfarrell>: looks like we are not using middleman-syntax so can add that and should get more inline with github style markdown [Mon May 11 18:27:02 2015] <kts>: it sounds like the site has the tools that will make the long-term vision achievable, should we focus on improving that [Mon May 11 18:27:02 2015] <kts>: 1. link to docs on the site, not github [Mon May 11 18:27:02 2015] <wfarner>: kts: by this you mean remove docs from the site? [Mon May 11 18:27:02 2015] <wfarner>: (not judging, just using direct wording) [Mon May 11 18:27:02 2015] <jfarrell>: github is a mirror, we shouldnt depend on a mirror for our docs [Mon May 11 18:27:02 2015] <kts>: wfarner: from this discussion I think we actually might want to deprecate github [Mon May 11 18:27:02 2015] <jfarrell>: +1, we dont use it for any of our other work flows [Mon May 11 18:27:02 2015] <dlester>: kts: was there a second option? :) [Mon May 11 18:27:35 2015] <davmclau>: Sounds like a discussion that might be better suited for the dev list [Mon May 11 18:27:39 2015] <jfarrell>: objections to moving the site into our codebase as say build-support/site (will look at this as an option if possible for us) [Mon May 11 18:28:16 2015] <kts>: jfarrell: im in favor, but sounds like we should open a discussion on dev@? [Mon May 11 18:28:36 2015] <jfarrell>: not sure if its possible with the way the new gitpubsub is setup [Mon May 11 18:28:36 2015] <wfarner>: kts dlester can one of you open this discussion on dev@ today? [Mon May 11 18:28:49 2015] <kts>: whatever we do it definitely won't work unless we have automation to ensure it's up-to-date [Mon May 11 18:28:55 2015] <kts>: currently only github offers this [Mon May 11 18:29:44 2015] <kts>: wfarner: I'll open one today [Mon May 11 18:29:55 2015] <kts>: #action kts to start discussion on documentation automation on dev@ [Mon May 11 18:29:57 2015] <wfarner>: kts: thanks! [Mon May 11 18:30:12 2015] <wfarner>: that exhausts my topics, does anyone else have a topic they would like to discuss? ## GSOC 2015 ## [Mon May 11 18:32:17 2015] <wfarner>: marti_: the floor is yours! [Mon May 11 18:32:28 2015] <marti_>: Hi! It is about this issue https://issues.apache.org/jira/browse/AURORA-1164 [Mon May 11 18:33:10 2015] <marti_>: and made this slides for some share ideas https://docs.google.com/presentation/d/1iIweOkBRnq7BtU_jhLEjhLjVtHEVuGwocc6lItcy5oU/edit?usp=sharing [Mon May 11 18:34:30 2015] <davmclau>: cool! do you mind soliciting feedback via the dev list? [Mon May 11 18:34:34 2015] <davmclau>: or maybe you already did that [Mon May 11 18:35:02 2015] <marti_>: yes I need feedback :D [Mon May 11 18:35:05 2015] <wfarner>: davmclau: he sent an intro e-mail, this is the first discussion about approach [Mon May 11 18:36:20 2015] <dlester_>: I'm mentoring marti_ this summer as he works on the Aurora web CLI tutorial, the google presentation shares some early ideas [Mon May 11 18:37:10 2015] <wfarner>: marti_: firstly, welcome! i'll be interested to see where this goes! [Mon May 11 18:37:22 2015] <marti_>: thanks ^_^ [Mon May 11 18:38:18 2015] <wfarner>: in this meeting we probably won't get into feedback/brainstorming, but please feel free to seek advice in this channel and on dev@! [Mon May 11 18:38:33 2015] <dlester_>: just to add a little context here that may not already be shared, this is a web-based tool that will live in a separate repo and hopefully will be general enough that it could be used by different projects. but our intent is to develop something for Aurora [Mon May 11 18:39:09 2015] <marti_>: ok I will open a topic in dev [Mon May 11 18:39:25 2015] <jcohen>: Iâm excited to see where it goes, thanks marti_! [Mon May 11 18:40:00 2015] <wfarner>: any other topics before we close? [Mon May 11 18:40:32 2015] <wfarner>: thanks for participating, everyone! [Mon May 11 18:40:34 2015] <wfarner>: ASFBot: meeting stop Meeting ended at Mon May 11 18:40:34 2015
