Posted	Nick	Remark
#openstack-sdks - 2017-05-16
15:41:27	mordred	so I _think_ I understood that dhellmann suggested we maybe make three different outputs that we publish - so we can point deployers at the info that's relevant to them without them needing to read about implementation internals or whatnot
15:41:30	mordred	or - something similar
15:42:42	edleafe	mordred: that sort of meshes with the feeling I had reviewing your discovery docs (besides the dizziness)
15:42:57	mordred	the dizziness means it's working
15:43:04	mordred	soon I will have the mind control overyou!
15:43:05	edleafe	mordred: that these aren't API guidelines, but more like deployment guidelines
15:43:06	mordred	wait
15:43:10	mordred	sssh. I didnt' say that
15:43:24	edleafe	or something like that
15:43:38	mordred	edleafe: exactly. I mean - they're API guidelines in as much as we want the API to behave in a way, and the deployers have to participate on a few topics
15:43:39	edleafe	I didn't hear that. I hear only what the master tells me to hear
15:43:44	mordred	edleafe: :)
15:44:31	edleafe	I think of these guidelines as helping the OpenStack developers make good choices when creating APIs
15:44:46	edleafe	These seem... different
15:45:32	mordred	do you think they seem different enough to put into a separate source repo? my original thought was "no" - since the corpus is about OpenStack REST APIs ...
15:45:49	mordred	but I am more than happy to agree with whatever opinions y'all have on that topic
15:46:46	edleafe	mordred: not really sure. I'd like to get cdent and elmiko to weigh in on this
15:47:39	mordred	cdent, elmiko: ^^ ?
15:47:58	cdent	I think putting creation and consumption in the same place is a good idea because it is more contextualized
15:54:37	dtroyer	++ separate sections in the same repo would be good with me, but having to look in multiple places to find thw whole story is just painful. More than a few of us fit multiples of those categories
15:55:55	dhellmann	mordred : we're working through whether it makes sense to have separate guides in the discussion with asettle about the future of docs
15:56:09	dhellmann	mordred : one option is to have 1 sphinx job that publishes nicely organized docs, but only one thing
15:56:22	dhellmann	another option is to have separate jobs, publishing different sets of docs to different places
15:57:19	dhellmann	there's more of a legacy concern there, because we want to deal with redirects if we change how things are published
15:57:20	dhellmann	if this is new content, you don't have that concern
15:57:34	dhellmann	so a single sphinx project publishing nicely organized content is more appealing
15:57:44	dhellmann	edleafe, cdent, dtroyer : ^^
15:58:48	cdent	ideally we'd see more places linking into the guidelines, and that makes even more sense if we're covering both creation and consumption
16:01:02	edleafe	cdent: +1
16:04:52	elmiko	mordred: edleafe, just saw the ping. reading back
16:06:46	elmiko	mordred: so, i more or less agree with cdent, edleafe and dtroyer. seems more useful to have things in a place that is easier to find
16:07:22	elmiko	i'm not sure what shape that would take, but i like the idea of being able to navigate between the different guideline types in a convenient fashion
16:10:21	mordred	sweet
16:11:28	edleafe	The only one that seems out of place a bit is the version discovery algorithm
16:11:45	edleafe	but in the context of the others, it fits
16:12:00	mordred	dhellmann: there is also at least one thing in the service-types-authority consumption spec that assumes we can publish the service-types-authority data to a location that will be solid/stable/well-known. It's currently written up as "https://specs.openstack.org/service-types.json" - which I think a job in s-t-a to publish post-merge should be easy enough to implement
16:13:00	dhellmann	mordred: it feels a little odd to publish machine-readable data to the root of the specs site, but I think I get it
16:13:28	mordred	dhellmann: yah - we could also spin up a new domain/web root for that I imagine too
16:13:55	cdent	i think specs could very well be fine: it's sort of like a spec
16:14:10	dhellmann	yeah, it's just a new precedent
16:14:11	cdent	and helps give it some ooomph
16:14:31	mordred	edleafe: maybe if we re-org that doc slightly more cleanly into "develop/deploy/consume" portions rather than "this is all the information you need about consuming versions - oh, also, deployers please take note of this bit" it'll be easier to read too?
16:19:27	edleafe	mordred: or maybe "here's where we are", "here's why we are in the state we are", and "here's where we really want to be"
16:20:21	mordred	edleafe: yes. "this is the description of the idea state" - "this is description of the complete current state including the ideal state" - "these are recommendations for people who would like to achieve future perfection"
16:20:41	mordred	edleafe, cdent, elmiko: WHILE I'VE GOT YOUR ATTENTION ...
16:23:57	mordred	most of the services I've found in openstack with microversions implementations use the nova form of version/min_version rather than the API-WG recommendation of max_version/min_version ... including nova, cinder, manila and ironic - although it seems magnum and zun have the min_version/max_version form
16:24:39	mordred	I'm mostly curious about the decision to recommend min/max (since I wasn't paying attentoin then) and how much effort we think should go in to adding max_version to the services which just have version?
16:25:42	mordred	(I started a patch to add a "collections" link as from the version discovery thing just to see how bad it was (not) which is what got me thinking about this specifically)
16:25:45	elmiko	iirc, some of these projects were impementing microversion while we were still arriving at the guideline, that combined with the "nova effect" (copy what nova did) did not help
16:26:35	elmiko	it would be cool to bring the project up to speed with the guideline, but i don't have a strong handle on how interested in taking on the tech debt they would be
16:26:58	elmiko	we don't get strong participation on a good day, it's just tough to know how the individual projects would feel about it
16:27:15	sdague	well nova, ironic, and manila were out the door before there ever was an api-wg recommendation
16:27:17	elmiko	my gut feeling is that it will be like herding a small pack of cats
16:27:20	mordred	I mean, from a consume perspective, any consumer is going to have to handle both choices no matter what for the forseeable future so it's not a super big deal there
16:27:26	elmiko	sdague: exactly
16:27:28	mordred	sdague: yah
16:28:00	edleafe	does anyone use max_version?
16:28:04	mordred	yes
16:28:12	elmiko	imo, it would be nice, but we (api-wg) don't exactly have a habit of chasing folks down to implement the guidelines
16:28:18	mordred	magnum and zun at least - I haven't taken full catalog yet
16:28:57	cdent	I thnk the change probably happeend because there's a conflict between the default version you get if you don't specific and the concept of "version"
16:28:59	cdent	I would expect "version" to mean "what i get if I say nothing"
16:29:02	mordred	elmiko: :) -- my next couple of months are going to be essentially chasing folks down to let me implement some of the guidelines ... so I'm kind of poking around the edges to figure out how it's gone so far
16:29:07	cdent	which would mean min_version
16:29:15	elmiko	mordred: ooh! neat =)
16:29:26	elmiko	in that case, +1 to adding them
16:29:26	mordred	elmiko: wish me luck!
16:29:41	cdent	so by being explicit about max, min, we avoid the confusion
16:29:53	edleafe	hmmm... maybe add a note to the microversion guideline about the existing services that don't follow
16:30:06	mordred	edleafe: I can do that in one of my next passes through the stack
16:30:44	edleafe	yeah, I mean, I know nova will never change this, so we should at least acknowledge reality
16:30:54	elmiko	edleafe: good point
16:31:04	cdent	we did manage to add support for openstack-api-version: compute x.y
16:31:17	cdent	so we may not ever remove the old way, but we can add the new way
16:31:53	edleafe	cdent: true, so maybe there's hope :)
16:36:16	elmiko	bbl
16:53:22	mordred	mugsie, sdague: the sub-elements patch has examples published herE: http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/ - versions and list-sever-details are both good examples to look at for output
16:53:52	mordred	I don't feel super strongly about this at all - it was more a thing I've hit up against before reading the docs so I thought I'd take a random stab at it
16:57:19	sdague	mordred: ok looking
16:57:36	sdague	mordred: have we gotten a read from horizon folks as to if they like this approach?
16:58:53	sdague	I think it has definite advantages, we probably need a good glossary explaining how to read it (maybe if we had a footnote added to the bottom of every table automatically)
16:58:58	mordred	sdague: I have not poked any of them but I can - what's the specific tie to horizon? (I may be missing context)
16:59:12	sdague	just, they are folks that tend to read our api-ref
16:59:22	sdague	honestly, I just want other readers
16:59:28	mordred	ah- gotcha. yes- they would be great additional inputs
16:59:39	mugsie	I agree with the problem statement - I am just not sold on the format
16:59:41	mugsie	but
16:59:45	mugsie	we could iterate that
16:59:48	sdague	because I'm so steeped in this that I don't trust my judgement on better/worse
17:00:40	sdague	if we had a couple of common consumers say "yes please", I'd be all for a "you betcha"
17:01:12	mugsie	mordred: where did the '[]' come from - for me that looks a bit wierd
17:01:13	mordred	I also am not sold on the format either- so feedback/suggestions from folks would be great
17:01:33	mordred	mugsie: servers is an array - so servers.name looked weird to me
17:01:41	sdague	mugsie: it is to distinguish array vs. object attr
17:01:45	sdague	which makes sense
17:01:56	mordred	yah. I also _think_ I got the idea from the GCE docs - but I might e lying about that
17:02:11	sdague	so, because json requires a top level key, I do wonder if we can shorthand past the first key
17:02:30	mordred	but it doesn't
17:02:41	mordred	we actually do have APIs in openstack that do not return top level keys
17:02:50	sdague	... o really....

Earlier   Later