16:00:46 #startmeeting api wg 16:00:46 Meeting started Thu Jun 18 16:00:46 2015 UTC and is due to finish in 60 minutes. The chair is elmiko. Information about MeetBot at http://wiki.debian.org/MeetBot. 16:00:48 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 16:00:49 bye 16:00:50 The meeting name has been set to 'api_wg' 16:01:13 #topic agenda 16:01:13 Aloha 16:01:16 o/ 16:01:17 .....0...../ 16:01:17 o/ 16:01:20 hi 16:01:22 * jaypipes comes running in... 16:01:30 o/ 16:01:31 #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda 16:01:31 o/ 16:01:33 jaypipes: lol 16:01:36 jaypipes: thought you had long arms :) 16:01:39 lots of stuff on the agenda today 16:01:49 edleafe: no, I just tripped running to the meeting,. 16:03:07 let's give folks a minute or two 16:03:16 o/ 16:03:45 i'm not sure on the freshness of our action item list, we'll see 16:04:22 #topic previous meeting action items 16:04:27 o/ 16:04:40 #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-06-04-16.00.html 16:05:01 i did both of mine 16:05:16 looks like the rest were between cdent and sdague, you guys wanna give updates? 16:05:39 elmiko: I did a pretty detailed review of the artifacts api in glance, I haven't looked at their follow up 16:05:48 sdague: awesome! 16:05:52 sdague and I made some comments on the glance api proposal. It felt a bit like a pileon but I think the input from everyone was useful. 16:06:10 I'm assuming our reviews of other project APIs are advisory, as in "we think this would be a better way to do it, but it's your API" 16:06:25 cdent: what's the sentiment on the api wg reviews? 16:06:29 i certainly hope it's taken that way 16:06:37 I don't think I scored my review for that reason 16:06:56 this was the revision everyone pretty much reviewed - https://review.openstack.org/#/c/177397/3/specs/liberty/artifacts-api.rst,cm 16:07:17 o/ 16:07:19 etoews: I haven't been able to get guage on reactions 16:08:01 yeh, there hasn't been an update yet to the review, so I don't know 16:08:10 hmmm...zero replies to the comments. 16:08:15 jaypipes you are a little closer to that team, any idea on how they are feeling about it? 16:08:46 sdague: they will align with the API WG guidelines.\ 16:08:52 cool 16:09:04 sdague: they've already stated as much. will have to align ex post facto, since they merged already, but they will align. 16:09:20 oh, the API is already merged? 16:10:05 mclaren and nikhil_k are the CPLs for glance 16:10:14 sdague: some of it is, yes, AFAIK. 16:11:25 do we have an action here, or just wait and see what happens with the review? 16:11:42 i think we're in wait and see mode at the moment 16:11:51 k 16:12:06 the other action I had was about changes-since: I dropped a question on the filtering spec about changes-since and got the expected reply: that something more generic is probably the right way to go and in any case whatever it is, not on that spec 16:12:34 so the question remains: do we want (and if we do who wants to) to formalize a mode of doing changes-since across all collection apis? 16:13:01 hi 16:13:41 cdent: how many apis is changes-since in? only nova comes to my mind. 16:13:49 glance also 16:14:13 https://review.openstack.org/#/c/192926/ is relevant to this topic 16:14:13 glance does. 16:14:19 cdent: by "changes-since" you mean give me the list of entities that were modified since a given date, correct? 16:14:35 miguelgrinberg: believe so 16:14:45 miguelgrinberg: yup. 16:14:52 then this is a query on the last_modified field 16:14:56 doens't Ceilo also have that? 16:14:59 why can't we treat it as a regular query then? 16:15:02 miguelgrinberg: as I understand it, yes, but I get the impression that changes-since has somewhat more magical semantics than modified_time>somedate? 16:15:19 don't know, what's special about it? 16:15:23 so the underlying question is: what are those magical semantics? 16:15:24 cdent: nope, that's pretty much the extent of it :) 16:15:26 cdent: speaking only of glance V1, it's magic was to include deleted rows 16:15:42 that's quite magic if they are _actually_ deleted :) 16:15:43 ah 16:15:58 cdent: welcome to the world of soft-delete. 16:16:01 for V2 glance that is to be supported via a status field filter 16:16:03 cdent: welcome to the world of soft-deletes 16:16:08 jaypipes: jinx 16:16:18 ha! 16:16:27 isn't there a wiki page about changes since somewhere? 16:16:28 * cdent looks 16:16:47 http://docs.openstack.org/developer/nova/v2/polling_changes-since_parameter.html 16:16:58 yeah, looks like nova also has some attention to things recently deleted as well 16:17:09 so presumably a simple attribute query would not have that? 16:18:16 you could ask for the last_modified *and* a state=active,deleted,whatever-else 16:18:16 thus the magic of changes-since...do we as a group care to enshrine that? 16:18:27 so we do it without magic 16:18:40 cdent: honestly, I think what a project decides it wants to return should be fine 16:18:43 cdent: I do not care to enshrine anything "magic" in our APIs, no. 16:18:47 I'm cool with that. Prefer it in fact. 16:19:00 miguelgrinberg: i like that approach, seems more explicit 16:19:07 I kind of like it as a more abstract changes-since concept that would be common accross projects 16:19:20 magic changes over time.... 16:19:23 miguelgrinberg: yes, exactly 16:19:26 sdague: as in "projects should implement changes-since"? 16:19:44 right on, good, this is the right outcome: filter with a combined query is more sensible 16:19:50 and comprehensible too 16:19:58 sigmavirus24: on resources that you expect to be polled, we recommend you implement this 16:20:00 isn't there only two states for the magic switch to be set to in OpenStack? "magic" and "more magic"? 16:20:06 sdague: that seems reasonable 16:20:13 sigmavirus24: lol 16:20:16 s/isn't/aren't/ 16:20:19 sdague: +1 16:20:23 because as a consumer having to know all the states I'm looking for explicitly is weird 16:20:35 I really semantically just want "tell me your changes" 16:20:44 "gimme your deltas" 16:20:47 right 16:20:55 (The new motto for Pull Requests as a Service) 16:21:06 it is up to the server to decide what is a valid change 16:21:08 and sure, it's a little less explicit, but it's really understandable from a consumer point of view 16:21:28 and the explicit filters might be there for those that care 16:21:29 so changes-since is ?state=neq:deleted&updated_at=gt: under the draft filter guidelines 16:21:34 don't need to know the states 16:21:53 stevelle: well in glance and nova it includes deleted 16:22:15 sdague: agreed 16:22:15 it should include everything if you don't say what states you want, that makes sense to me 16:22:35 but it should be consistent with other queries, IMHO 16:22:39 and if you do care about specific states, then you can ask about it 16:22:40 sdague: wouldn't that just be ?updated_at=gt: ? 16:23:22 (following miguelgrinberg's state logic) 16:23:42 miguelgrinberg: including deleted by default seems weird 16:23:56 so, honestly, my feeling is that depending on the resource, returning deleted may or may not make sense, and the server probably knows better about that 16:23:57 (meant to have a ? on the end of that) 16:24:26 which is why I kind of like leaving that decision up to the implementation on a point basis with changes-since 16:24:29 if there is a "deleted" state, then those entities need to be returned if the client didn't explicitly take them out 16:24:57 sdague: that inconsistency of expectation is exactly what makes me uncomfortable about changes-since 16:25:03 don't like that idea of doing implicit filtering based on what query the client is requesting 16:25:14 we give clients the explicit filters 16:25:17 they can do that thing 16:25:26 we should probably move on from this in another minute or two. it can continue to be discussed in #openstack-api afterwards. 16:25:32 etoews: +1 16:25:37 etoews++ 16:25:47 mabye a mailing list post 16:25:49 this is a value judgement call from the resource about "here's what we think you need" 16:25:51 sure 16:26:12 each time I bring this up I'm always surprised at how much chat it generates 16:26:13 #action start a mailing list thread about changes-since topic 16:26:25 moving on 16:26:26 and what 'deleted 16:26:28 ugh 16:26:34 elmiko: who's got that action? 16:26:36 what 'deleted' means 16:26:42 oops, good point 16:26:53 cdent: you wanna start that thread? 16:27:05 Sure, as long as I'm allowed to be ignorant and hand wavey 16:27:16 lol, of course ;) 16:27:18 #action cdent start a mailing list thread about changes-since topic 16:27:26 ✔ 16:27:30 #topic weekly newsletter 16:27:36 etoews: i think this was from you? 16:27:42 yep 16:28:11 so i really want to start up a weekly newsletter for the api wg ala "What's Up Doc?" 16:28:20 a fine idea 16:28:48 summarize our activity weekly for better visibilty and information dissemination 16:29:26 a great idea, but where do people find the time? 16:29:44 can it be auto-generated from reviews,etc. At least part of it? 16:29:45 i don't know much about the generation of "What's Up..", do they use a template or something? 16:29:49 cdent: find the time for what exactly? 16:30:05 add yet another thing to do (like manage a newsletter) 16:30:15 miguelgrinberg: yep. i was thinking about auto-generating parts of it. 16:30:31 etoews: would it mainly be advertising things in freeze and recently merged? 16:30:34 so, honestly, auto generated english basically gets deleted by people 16:30:46 cdent: if i can nail down some automation with gerrit 16:31:01 that would make it much easier 16:31:06 if there is a desire to be effective, it should be manually currated and entertaining, and done less often 16:31:10 otherwise it's just spam 16:31:28 sdague: i'd only be generate a "by the numbers" section 16:31:37 sdague: how frequently would you recommend? 16:31:41 the rest is manually currated and entertaining 16:31:51 so, weekly seems like pretty often 16:32:03 I'd be more inclined to say every 3 or 4 weeks 16:32:09 so that there is enough content in it 16:32:30 one of the reasons i was thinking weekly was that we could roll the "Guidelines ready for cross project review" into the newsletter 16:32:45 sdague: that makes some sense and addresses cdent's comment 16:32:47 and the "Finalized guidelines" too 16:33:22 etoews: but the entertaining content might suffer on a weekly release, ie might get bothersome after a few months. 16:33:23 etoews: guideliens ready is a call to action yes? 16:33:32 whereas the rest of it is kind of news and such 16:33:46 having those two in the same place is a way to ensure that the call to action isn't acted upon, unfortunately 16:33:46 cdent: yes 16:34:18 I think as a starting point the best value for effort is to automate the call to action 16:34:21 * etoews ponders 16:34:22 and see where that gets us 16:34:46 (people can always respond to that email if they want to gossip etc) 16:34:51 i'm cool with that for a start, we need it anyway with all the guidelines that are coming 16:35:45 yes. it's not easy to know what state the reviews are in at a glance. 16:36:09 okay. i'm willing to experiment a bit with this. 16:36:14 cool 16:36:16 etoews++ 16:36:48 #action etoews experiment with creating a guideline status mailing list update 16:36:52 sound good? 16:37:28 more like "...a api wg mailing list update" 16:37:48 will undo remove the last action? 16:37:52 but fine to leave as is 16:38:23 does anyone have any experience working with the openstack gerrit api? 16:38:33 (let's discuss that after and move on) 16:38:39 k 16:38:43 etoews: yeh, ping me in channel 16:38:47 #topic merge the merge process? 16:39:07 i'm +1 on this, we got really solid and positive response after the initial ML post 16:39:45 any objections? 16:40:00 nope 16:40:07 i'll fix up the minor stuff in another patch. 16:40:30 cool, +workflowed 16:40:36 i don't want disrupt the current green forest of +1s 16:40:41 hehe 16:40:47 elmiko: thx 16:40:57 #topic guidelines 16:41:22 so we have 3 that have been recommended for freeze, and 2 that need a re-review i think 16:41:44 #link https://review.openstack.org/#/c/183694/ 16:41:54 #link https://review.openstack.org/#/c/177468/ 16:42:01 #link https://review.openstack.org/#/c/181931/ 16:42:09 +1 on freezing the candidate freezers 16:42:13 those have all been put forward as freezeable 16:42:46 elmiko: btw, freeze means -1 on workflow. not -2 code review. 16:43:04 ryanb isn't here, but i think 177468 might need another fix 16:43:17 etoews: ack, i'll adjust my process. sorry bout that 16:43:23 np 16:44:04 jaypipes: can you respond to doug's comment in https://review.openstack.org/#/c/179365/3/guidelines/http.rst ? 16:44:22 so, should we go another round of consensus on the 177468 review before moving to freeze? 16:44:30 (plus it needs a bug fix) 16:44:31 elmiko: yep, will do. 16:45:33 #action jaypipes respond to comments on #link https://review.openstack.org/#/c/179365/ 16:46:06 is alex here? 16:46:24 Something I think we all need to be aware of is that as soon as any guideline is actually out there in the published world people are going to find all kinds of issues with it, so we may as well keep the process of publication as friction free as possible and instead insure that we have a robust process of post-merge review 16:46:28 ping alex_xu 16:46:43 cdent: +1 16:47:14 i think alex_xu and bknudson were having a conversation on that one, needs some resolution 16:47:17 gerrit kind of works against reviewing existing stuff, but with narrative especially it is critical that we are constantly reviewing master 16:47:23 elmiko: done with that action item. 16:47:30 it's middle of the night for alex_xu 16:47:38 jaypipes: lol, fast! 16:47:43 ah ok 16:47:48 fwiw 177468 has another fix in 16:47:52 we'll push that one till next time 16:47:59 stevelle: oh, very cool 16:48:08 so, we'll freeze the 3 listed then. 16:48:29 if a guideline author does decide to do a minor type/fix and erase all of the +1s, how do we track the +1s from the previous patch set to know that it's okay to merge? 16:48:53 etoews: man... that's a darn good question 16:49:08 etoews: all the comments are still there 16:49:22 but not the +1s AFAICT 16:49:31 the comments have the vote in them 16:49:41 you can still read them 16:50:10 ah. i see. 16:50:36 conceivably you could automate that (if the api supports it) 16:51:06 automate displaying the +1s of the previous patch set that is 16:51:14 let's move on 16:51:16 etoews, jaypipes, does one of you want to freeze those reviews and make the ML announce? 16:51:36 etoews: feel free to freeze. 16:51:42 hehe 16:51:48 #action etoews to freeze the 3 review and announce on ML 16:51:52 cool 16:51:56 thanks 16:52:12 #topic APIImpact 16:52:22 sigmavirus24: you had a note here 16:52:37 #link https://review.openstack.org/191542/ 16:53:49 oh sorry 16:54:04 So that spec is mostly a security measure for glance 16:54:23 That said, it'll change change somethings about representations in the API 16:54:44 If you look at L57 and ignore the untrimmed trailing whitespace 16:55:20 You'll see what the proposal currently recommends, which I'm not convinced is actually correct, but there's some precedent for it (specifically how Amazon does this) 16:55:39 I give some reasoning around L70 though that the API-WG should like so .. eh 16:55:53 Mostly, I want feedback around the API Impact of the change 16:56:31 does "Content-" give enough uniqueness to the header? 16:56:45 Yeah that's my concern 16:56:57 Not sure I can think of a different way to do it though 16:57:03 maybe just tack an OpenStack- on the front? 16:57:07 The most common variant of that is Content-MD5 16:57:14 Yeah but it's not really OpenStack specific 16:57:17 ahh 16:57:33 Content-SHA256 shouldn't ever conflict with anything else 16:57:38 But maybe it will? 16:58:00 In reality, I'd expect either Content-SHA2 or Content-SHA256 for that header 16:58:18 make sense to me 16:58:24 okay 16:58:47 1 minute left, any last thoughts? 16:58:53 Beer. 16:58:57 +1 16:59:06 the artifacts API in glance is EXPERIMENTAL for now 16:59:07 jaypipes: can you send me one please 16:59:19 nikhil_k: I am 100% opposed to experimental APIs. 16:59:26 so that we can adjust variations suggested but not many 16:59:27 cdent: will do! :) 16:59:48 yeh, experimental is useless construct. Once things are out in the world, they get used. 16:59:49 would beta be a better term? 16:59:51 jaypipes: we are working on making it non-experimental this cycle (hopefully) 16:59:52 nikhil_k, jaypipes, we need to take this to openstack-api for further talk 16:59:58 nikhil_k: experimental APIs are a tried and true way of having nothing tried and true in your API. :) Trusst me, we tried that with Nova v3 17:00:03 thanks everyone! 17:00:08 #endmeeting