21:02:46 <bcwaldon> #startmeeting
21:02:47 <openstack> Meeting started Fri Dec  9 21:02:46 2011 UTC.  The chair is bcwaldon. Information about MeetBot at http://wiki.debian.org/MeetBot.
21:02:48 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic.
21:02:53 <bcwaldon> well let's get started anyways
21:03:04 <bcwaldon> #topic OpenStack Compute API versioning and extensions
21:03:26 <bcwaldon> so I *thought* I had a good idea of where we want to go with this, but Mr. Williams had to go and screw it all up ;)
21:03:46 <jorgew> ..actually it's Dr. Williams :-)
21:03:54 <jorgew> lol, sorry man
21:04:01 <bcwaldon> no worries!
21:04:31 <bcwaldon> so I'm going to spend some time this weekend and come up with a draft versioning proposal for OpenStack Compute
21:04:54 <bcwaldon> Looking to collaborate with jorgew early next week on that
21:05:10 <jorgew> That sounds good…I'm looking forward to it
21:05:10 <bcwaldon> #action bcwaldon to write up versioning proposal
21:05:17 <annegentle> bcwaldon: got a high-level overview for that proposal?
21:05:34 <annegentle> bcwaldon: as if I'm a kindergartner? :)
21:05:38 <bcwaldon> annegentle: something along the lines of what mnot proposed a month or so back on the ML
21:05:54 <annegentle> bcwaldon: ok, will look for the link for the notes
21:06:04 <bcwaldon> At a super hight level, versioning our compute api solely by mimetypes
21:06:43 <bcwaldon> and treating each resource somewhat individually w.r.t. versioning
21:06:51 <bcwaldon> it's hard to explain...
21:07:10 <annegentle> s'ok
21:07:11 <bcwaldon> so I was hoping for some discussion here
21:07:19 <bcwaldon> but if its just the three of us...
21:07:29 * bcwaldon waits to see if anyone is lurking
21:07:40 <annegentle> heckj: around?
21:07:44 <jorgew> heck:?
21:08:19 <bcwaldon> well, I guess we'll move on and defer this discussion to the ML next week
21:08:30 <jorgew> sounds good.
21:08:32 <bcwaldon> so annegentle, do you want to discuss extension docs?
21:08:39 <bcwaldon> #topic Extension Documentation
21:09:26 <annegentle> sure
21:09:44 <jorgew> BTW, anne thanks for the comments on the list…haven't had a chance to reply but I'm with you on most/all points
21:09:47 <annegentle> I think I rounded up my thoughts in a note to the mailing list
21:10:06 <bcwaldon> ok, anything you want to bring up in particular? Feel free to say no :)
21:10:13 <annegentle> just a sec...
21:10:43 <annegentle> was going to say, Jorge has agreed to most all the items
21:10:51 <annegentle> some of it we have to have more input on
21:11:14 <annegentle> I went to the OpenStack-Austin meetup last night and then emailed it to a few folks from there
21:11:24 <annegentle> didn't get in person feedback then but solicited more input
21:11:58 <annegentle> really what heckj brought up about related-ness to the API site is probably the biggest question out there now
21:12:08 <jorgew> Right.
21:12:17 <annegentle> and my other "concern" is about how it's like pulling teeth to get the stuff written. :)
21:12:17 <jorgew> I think that we have a need for user guides
21:12:27 <jorgew> …and that's not what's out there
21:12:39 <jorgew> this is just documenting how each extension changes the API
21:12:45 <jorgew> sorta like a spec.
21:12:50 <annegentle> jorgew: right, so the two issues are related, the authoring side and the display side
21:13:09 <bcwaldon> I would really like to block reviews that add extensions w/o some level of documentation
21:13:12 <annegentle> jorgew: or we just call them unrelated and I recruit both types of content
21:13:24 <jorgew> What's the issue with the authoring side, cus honestly think things are getting better in that dept
21:13:26 <bcwaldon> if we can make it easy for people to provide that documentaiton, I think its 100% doable
21:13:36 <annegentle> bcwaldon: that's a good point too, the governance of both the extension and their docs needs defining
21:13:41 <jorgew> bcwaldon: for sure.
21:13:59 <jorgew> Right I agree.
21:14:26 <bcwaldon> so that might just be something I need to enforce within Nova
21:14:33 <jorgew> I think if we give people more of an incentive to write docs will get written
21:14:44 <bcwaldon> annegentle: can you send me the details of what exactly you want from extension authors?
21:14:52 <annegentle> bcwaldon: and finding a small team of enforcers so there's distribution of work
21:15:02 <jorgew> annegentle: right
21:15:03 <annegentle> bcwaldon: so I've got a contribution coming in January from a writer at HP
21:15:18 <annegentle> he basically wrote dev-guide style docs for floating ups, etc
21:15:27 <annegentle> IPs that is
21:15:57 <annegentle> so it's more instructive for api users than instructive to a reader to revise the spec
21:16:11 <annegentle> we've had to reuse specs as dev guides
21:16:23 <annegentle> but really it is time to create real dev guides
21:16:36 <annegentle> I think we're gathering some resources to do so - HP needs it for sure too
21:16:41 <annegentle> and Rackspace is hiring
21:16:42 <bcwaldon> that's awesome
21:16:51 <jorgew> annegentle:  I agree, we need more dev guides
21:16:54 <bcwaldon> A lack of resources is probably the biggest pain point right now
21:16:55 <annegentle> so it's a matter of matching up the doc with the audience
21:17:22 <annegentle> bcwaldon: what I'm hoping is we'll get an influx in January, and I'd like to be able to tell people we're being strategic about placement
21:17:26 <jorgew> annegentle: But we also need info on how an extension modifies a spec.  Their not mutually exclusive
21:17:36 <annegentle> jorgew: absolutely, both are needed
21:17:36 <bcwaldon> ok, so the developer himself is probably the main consumer of any specific extension doc
21:17:49 <annegentle> I just can't prioritize spec doc over user docs :)
21:17:58 <annegentle> as far as resource planning
21:18:05 <jorgew> Well we need both
21:18:22 <jorgew> and usually the spec comes first … it informs the user doc
21:18:26 <bcwaldon> annegentle: maybe this is something we need to talk about in the meeting on monday
21:18:38 <bcwaldon> annegentle: I've just come up with a whole bunch of questions I want to ask :)
21:18:39 <jorgew> it would suck to write user docs while a spec is in flux
21:18:46 <annegentle> yeah priorities are certainly worth prioritizing
21:19:07 <annegentle> er, discussing
21:19:18 <annegentle> I think both are needed by Esse
21:19:18 <jorgew> :-)
21:19:20 <bcwaldon> So since we're in a 'nova-api' meeting, what would you say to the members of this team
21:19:20 <annegentle> Essex
21:19:38 <bcwaldon> Right now I'd say the members are mainly developers
21:19:46 <annegentle> this team could give input on both sites - Extension and API - that'll help lay out tasks
21:20:11 <annegentle> basically this team can review
21:20:29 <annegentle> yeah? I'm just looking for ways to lay out the work
21:20:31 <bcwaldon> right, and wouldn't the members of this team be the ones writing the extensions themselves?
21:20:50 <bcwaldon> assuming this team has a larger dev representation
21:21:09 <annegentle> bcwaldon: yep and the docs to go with it and reviewing each other's stuff
21:21:27 <bcwaldon> right, so every aspect of extensions are basically contained within this team
21:21:35 <annegentle> bcwaldon: cool
21:21:47 <bcwaldon> would I be correct in saying that if we had a wiki on how to write an extension, that would help the devs help you?
21:22:03 * heckj reads scroll back really quickly
21:22:11 <annegentle> bcwaldon: yes and also describing the method that an extension becomes core
21:22:22 <annegentle> method/process/governance? Not sure what it really is.
21:22:26 <bcwaldon> it could cover the technical side, obviously, but then offering resources for documentation that can be handed off to the docs team when complete
21:22:26 <annegentle> hi heckj!
21:22:32 <jorgew> bcwaldon: have you taken a look at the templates I put together?  From a spec perspective, I think most of what we need can be gathered from there.
21:22:37 <heckj> Hi! Sorry - had to run out just before this started. Just landed
21:22:55 <bcwaldon> jorgew: I haven't had a change to (not other than what Anne showed me)
21:22:59 <annegentle> bcwaldon: I don't really see a handoff necessarily, since there aren't resources.
21:23:24 <bcwaldon> by 'resource' I meant templates
21:23:32 <bcwaldon> but yes, I guess but handoff I mean mergeprop
21:23:36 <bcwaldon> by*
21:23:37 <jorgew> bcwaldon: links at the bottom of the extensions page
21:23:55 <bcwaldon> jorgew: where *is* that extensions page
21:24:03 <bcwaldon> jorgew: or are you talking about the one you sent to me to review
21:24:11 <bcwaldon> I'm so lost
21:24:35 <jorgew> http://docs.rackspace.com/openstack-extensions/
21:24:41 <heckj> Sorry - I'm not tracking. What's the topic?
21:24:49 <heckj> Ah!
21:24:56 <jorgew> heckj: extension and documentation
21:25:12 <annegentle> #link http://docs.rackspace.com/openstack-extensions/
21:25:13 <heckj> jorgew: I like the implementation of what you're doing there, but the idea is flawed from a usability perspective
21:25:34 <heckj> You have to know to read the main docs and all the extensions
21:25:39 <jorgew> heckj:  this isn't user docs, it's specs
21:25:46 <heckj> just to find what you're trying to do, or to see if you even CAN do it
21:26:00 <jorgew> heckj: we were just talking about how we need both docs and specs
21:26:10 <heckj> could you quickly summarize what a "spec" is for me then?
21:26:12 <jorgew> or rather guides and specs
21:26:30 <bcwaldon> jorgew: ok, why is that docs site on 'rackspace.com'? Why not openstack.org?
21:27:08 <annegentle> bcwaldon: at the time the team designed it, extensions we weren't certain extensions were accepted by the PPB
21:27:11 <jorgew> heckj: from an extensions prespective it defines specifically how the extension has changed the spec…to the point that an implementor can modify an implementation
21:27:20 <heckj> jorgew: because when I look it at, I thought it was additional documentation on the API
21:27:28 <bcwaldon> annegentle: ok, any plan on migrating to openstack.org?
21:27:56 <jorgew> heckj:  Yea I understand the confusion.  In the past our user guides and our specs were the same document.  That needs to change
21:28:22 <annegentle> bcwaldon: sure, we could do that if the community and PPB believe it to be maintainable and useful, it's really in a review stage now
21:28:32 <jorgew> heckj: so we should rename the title
21:28:39 <bcwaldon> annegentle: ok, just curious :)
21:28:47 <annegentle> bcwaldon: yeah it's a good question
21:28:50 <heckj> so the goal of the spec - an example of such being http://docs.rackspace.com/openstack-extensions/compute/os-bs/content/ch02s03.html, is that this is place where someone implementing the spec would go to read on what should be implemented?
21:29:20 <jorgew> heckj: or a user that wants to know exactly how the spec has changed
21:29:58 <heckj> So you want to keep a living history of how the API has changed over time with a series of these specs available for someone to read and review?
21:30:35 <jorgew> heckj: Well, not all extension are going to be available in all deployments.
21:31:00 <jorgew> heckj: Take a look at http://docs.rackspace.com/openstack-extensions/apix-intro/content/Overview.html
21:31:13 <jorgew> for an overveiw of extension mechanism
21:31:21 <annegentle> heckj: Rackspace and HP have to provide docs that include what extensions they have in their deployment
21:31:45 <annegentle> heckj: and others who have public or private OpenStack clouds
21:31:48 <jorgew> heckj: what's actually in a deployment is a combination of the core and 0 or more extensions
21:32:03 <bcwaldon> Real quick guys, I think we're done with the nova-api meeting. I'm going to end it if nobody else has anything related
21:32:13 <bcwaldon> keep this discussion going though :)
21:32:36 <annegentle> bcwaldon: oh I did want to hear about the versioning
21:32:50 <annegentle> bcwaldon: are we still doing a 1.1 > 2.0 rename
21:33:03 <annegentle> bcwaldon: and can extensions be brought in at all?
21:33:21 <annegentle> you may have answered this already but thought others could benefit from my confusion being clarified
21:33:22 <bcwaldon> #topic v1.1 -> v2 rename
21:33:40 <bcwaldon> ok, so I'm fine doing a true rename, but I think it's easier to not do it
21:33:44 <annegentle> to rephrase my last question, can extensions be brought to core in the essex time frame
21:33:56 <bcwaldon> hold on
21:34:07 <heckj> annegentle: ++
21:34:12 <bcwaldon> jorgew: do you see any problems with an actual rename?
21:34:17 <jorgew> annegentle:  I don't think it's possible to move all of those extension to core.
21:34:27 <heckj> why not?
21:34:30 <jorgew> bcwaldon:  I'm okay with the rename.
21:34:49 <bcwaldon> annegentle: what were your concerns with a rename
21:34:59 <jorgew> heckj: because core functionality is stuff that you can expect in all deployments
21:35:10 <annegentle> re: extensions moving to core, Just wondering if any extensions would move how many, what timeframe, etc. It affects user doc.
21:35:21 <heckj> yes - and there's a LOT in the extensions that can or should be in every reasonable deployment
21:35:34 <annegentle> re: rename, the more I look at how many files are affected and the work needed, I'm concerned about how to get a rename done.
21:35:42 <jorgew> heckj:  That's great, we should work towards promoting those features.
21:35:46 <bcwaldon> annegentle: yes, that's what I'm concerned about too
21:36:09 <bcwaldon> annegentle: what ramifications are there if we don't rename anything and just release the next set of docs with a big '3' on it?
21:36:21 <annegentle> yes I agree with heckj many of the nova api ext are just expected
21:36:47 <annegentle> bcwaldon: to me, none, but I'm new to this, haven't done a deployment, etc.
21:36:48 <bcwaldon> as for moving extensions in, we essentially have to design them into our next iteration of the api
21:36:49 <jorgew> bcwaldon: I'm also okay with leaving the API name 1.1 :-)  Really how big the impact will be depends on what our versioning scheme is. can we wait until that gets settled first before we decide
21:37:01 <bcwaldon> jorgew: yeah, that's what i'm leaning towards
21:37:16 <bcwaldon> annegentle: let's table the rename discussion until we have a greater consensus on versioning
21:37:27 <jorgew> bcwaldon: Right, we need a major version change to bring an extension in
21:37:30 <jorgew> to core
21:37:31 <annegentle> bcwaldon: sure, sounds good
21:37:31 <heckj> bcwaldon: seems reasonable
21:37:32 <bcwaldon> #topic Extension Promotion path
21:38:06 <bcwaldon> yeah, so an extension should live in the context of a single major version
21:38:15 <bcwaldon> this extension extends version 2
21:38:26 <bcwaldon> the need for that extension may go away in version 3
21:39:02 <jorgew> bcwaldon:  that's true
21:39:15 <jorgew> bcwaldon: but the extension may stick arround version 3 as well
21:39:28 <bcwaldon> sure, but it shouldn't be assumed to
21:39:54 <bcwaldon> does that make sense to everybody?
21:39:57 <jorgew> right.  That's why extension are detectable… you dont assume that they are there you can detectem with /extension
21:40:38 <annegentle> bcwaldon: can you walk through it with Floating IPs for example?
21:40:44 <bcwaldon> annegentle: sure
21:40:57 <bcwaldon> so in v2 right now, we have a floating ips extension that adds 2 actions to /servers
21:41:16 <bcwaldon> when we design v3, let's assume we decide to add it as a core feature
21:41:44 <bcwaldon> when we release the v3 spec, floating ips will already have been accounted for, so there is no extension necessary
21:42:02 <bcwaldon> if we decide *not* to include floating ips in v3, a new extension will have to be added
21:42:21 <bcwaldon> the reason there is that the api design may change in such a way that the old v2 extension doesn't make sense
21:42:44 <annegentle> so dev does work in /nova to move floating IP functionality from the contrib dir, it gets reviewed and in to trunk.
21:42:45 <bcwaldon> OR, that extension may *not* need to change if we don't make any breaking changes in the part of the spec that it extends
21:42:55 <bcwaldon> yes
21:43:00 <annegentle> then docs get added to indicate this is in core?
21:43:18 <bcwaldon> the v2 extension doc can hang around
21:43:27 <bcwaldon> and the v3 core spec will have the floating ips in it
21:44:26 <annegentle> ok
21:45:09 <bcwaldon> annegentle: did you have anything else you wanted to discuss?
21:45:27 <heckj> bcwaldon: process makes sense, thanks
21:45:31 <annegentle> bcwaldon: nope, thanks it's very helpful for my planning purposes
21:45:46 <bcwaldon> jorgew: anything to add?
21:46:01 <jorgew> no I think that makes sense
21:46:11 <bcwaldon> ok, any other topics of discussion?
21:47:06 <bcwaldon> alright, thanks for attending!
21:47:11 <bcwaldon> #endmeeting