| *** oomichi has joined #openstack-api | 00:32 | |
| *** salv-orlando has joined #openstack-api | 05:47 | |
| *** alex_xu_ is now known as alex_xu | 06:14 | |
| *** salv-orlando has quit IRC | 06:39 | |
| *** oomichi has quit IRC | 06:42 | |
| *** oomichi has joined #openstack-api | 06:44 | |
| *** oomichi_ has joined #openstack-api | 07:33 | |
| *** oomichi has quit IRC | 07:35 | |
| *** salv-orlando has joined #openstack-api | 07:39 | |
| *** salv-orlando has quit IRC | 07:44 | |
| *** alex_klimov has joined #openstack-api | 08:12 | |
| *** alex_klimov has quit IRC | 08:28 | |
| *** salv-orlando has joined #openstack-api | 08:45 | |
| *** e0ne has joined #openstack-api | 08:46 | |
| *** cdent has joined #openstack-api | 08:48 | |
| *** fzdarsky_ has joined #openstack-api | 08:48 | |
| *** salv-orlando has quit IRC | 08:53 | |
| *** e0ne has quit IRC | 08:55 | |
| *** fzdarsky_ has quit IRC | 08:57 | |
| *** e0ne has joined #openstack-api | 08:57 | |
| *** fzdarsky has joined #openstack-api | 08:57 | |
| *** fzdarsky has quit IRC | 08:59 | |
| *** fzdarsky has joined #openstack-api | 08:59 | |
| *** openstack has joined #openstack-api | 09:19 | |
| *** alex_klimov has joined #openstack-api | 10:53 | |
| *** e0ne has quit IRC | 11:21 | |
| openstackgerrit | Ken'ichi Ohmichi proposed openstack/api-wg: Add introduction for API microversion guideline https://review.openstack.org/187112 | 11:28 |
|---|---|---|
| openstackgerrit | Ken'ichi Ohmichi proposed openstack/api-wg: Add versioning guideline for API microversions https://review.openstack.org/243041 | 11:28 |
| *** e0ne has joined #openstack-api | 11:30 | |
| *** jaypipes has joined #openstack-api | 11:41 | |
| *** cdent has quit IRC | 11:54 | |
| *** alex_klimov has quit IRC | 12:11 | |
| *** alex_klimov has joined #openstack-api | 12:12 | |
| *** ig0r__ has joined #openstack-api | 12:17 | |
| *** lucasagomes is now known as lucas-hungry | 12:49 | |
| *** salv-orlando has joined #openstack-api | 12:52 | |
| *** salv-orlando has quit IRC | 12:56 | |
| *** _elmiko is now known as elmiko | 13:20 | |
| *** e0ne has quit IRC | 13:23 | |
| *** e0ne has joined #openstack-api | 13:37 | |
| *** cdent has joined #openstack-api | 13:54 | |
| *** salv-orlando has joined #openstack-api | 13:58 | |
| *** lucas-hungry is now known as lucasagomes | 14:00 | |
| *** khazelton has joined #openstack-api | 14:26 | |
| *** khazelton has quit IRC | 14:37 | |
| *** annegentle has joined #openstack-api | 14:49 | |
| *** salv-orlando has quit IRC | 15:02 | |
| *** openstackgerrit has quit IRC | 15:17 | |
| *** openstackgerrit has joined #openstack-api | 15:17 | |
| *** vishwanathj has joined #openstack-api | 15:22 | |
| *** salv-orlando has joined #openstack-api | 15:27 | |
| *** salv-orlando has quit IRC | 15:28 | |
| *** krotscheck has joined #openstack-api | 16:06 | |
| *** woodster_ has joined #openstack-api | 16:07 | |
| *** salv-orlando has joined #openstack-api | 16:09 | |
| *** alex_klimov has quit IRC | 16:16 | |
| *** e0ne has quit IRC | 16:26 | |
| *** salv-orlando has quit IRC | 16:33 | |
| *** e0ne has joined #openstack-api | 16:34 | |
| *** cdent has quit IRC | 16:39 | |
| etoews | holla elmiko! | 16:56 |
| etoews | i looked at the work you did on links https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Links | 16:57 |
| elmiko | etoews: cool, i think i could add a few more services | 16:58 |
| etoews | seems the predominant style in openstack is the Link Description Object http://json-schema.org/latest/json-schema-hypermedia.html#anchor17 | 16:58 |
| etoews | i was going to go ahead and use that style for the errors guideline https://review.openstack.org/#/c/167793/ | 16:59 |
| elmiko | +1 | 16:59 |
| etoews | cool. | 16:59 |
| elmiko | it seems like that is the main common denominator, although there are other custom uses | 16:59 |
| elmiko | etoews: did you happen to check out https://etherpad.openstack.org/p/mitaka-api-wg-session-plans ? | 17:02 |
| elmiko | i tried to capture some notes from the session we had | 17:02 |
| etoews | i haven't yet. i'll give it a read today or tomorrow. | 17:05 |
| elmiko | thanks, some food for thought for an upcoming meeting ;) | 17:05 |
| *** e0ne has quit IRC | 17:09 | |
| *** krotscheck has quit IRC | 17:12 | |
| *** krotscheck has joined #openstack-api | 17:29 | |
| sdague | etoews: LDO doesn't seem to make anysense here | 17:30 |
| sdague | because ref is mandatory | 17:30 |
| sdague | LDO is about describing links to other resources in relation to this resource | 17:30 |
| sdague | we're not considering documentation in html to be a resource of the server, it's external | 17:31 |
| elmiko | interesting | 17:31 |
| etoews | sdague: indeed it's external but a resource that relates to this error resource nonetheless. | 17:33 |
| sdague | the error isn't a resource | 17:33 |
| * etoews ponders | 17:34 | |
| sdague | what's the URL of the error on the server | 17:34 |
| sdague | if it doesn't have one, it's not a resource | 17:34 |
| etoews | that's exactly where my mind jumped | 17:34 |
| etoews | it's a sort of ephemeral resource | 17:35 |
| sdague | I think that's really stretching the metaphor | 17:35 |
| etoews | which is why request_id makes more sense than id | 17:35 |
| etoews | okay. so semantics aside. we want to provide a link as part of the error where the user can get help. | 17:36 |
| sdague | etoews: yep, definitely want to provide a link | 17:36 |
| sdague | that link should be to docs.openstack.org in some standard way | 17:36 |
| etoews | i simply lean towards that standard way being an already established standard way. i.e. LDO | 17:37 |
| etoews | why invent another linking structure? | 17:37 |
| sdague | what is the rel="" | 17:38 |
| etoews | rel="help" | 17:38 |
| etoews | http://www.iana.org/assignments/link-relations/link-relations.xhtml | 17:38 |
| sdague | ok, I guess I can get behind help | 17:39 |
| sdague | I didn't realize that was an option here | 17:40 |
| sdague | if rel="help", I'll drop my objections to LDO | 17:40 |
| etoews | cool. ya, i always intended it to be "help" but hadn't communicated that out yet. | 17:40 |
| sdague | yeh, that's where I was stuck | 17:41 |
| sdague | we should also probably convince people that help is the right rel for version docs | 17:41 |
| sdague | nova is currently using describedby, which isn't right for things that aren't a schema | 17:41 |
| sdague | https://github.com/openstack/nova/blob/e52d236a3f1740997890cad9d4726df01d5a7e5d/nova/api/openstack/compute/versions.py#L43-L49 | 17:42 |
| etoews | were you still thinking links should be a required field? | 17:42 |
| sdague | I do | 17:43 |
| sdague | because I think that if you are going down this path to provide structured errors back, you better be user documenting them | 17:43 |
| etoews | i'm just concerned about an OpenStack contributor needing to propagate an error out through the API but not having a helpful href on hand to include | 17:44 |
| etoews | i suppose the fallbacks could be docs.openstack.org or ask.openstack.org | 17:44 |
| etoews | if they don't have something that fits their error condition. | 17:45 |
| sdague | so, the way I see this going down | 17:46 |
| *** apoorvad has joined #openstack-api | 17:46 | |
| sdague | if a project wants to move to structured errors like this, they need to also have a docs tree that's publishing to docs.openstack.org with that info | 17:47 |
| elmiko | that would be awesome | 17:47 |
| sdague | so a new error is added, and the commit adding the error to the code would also do so to the docs | 17:47 |
| etoews | sdague: that's definitely the ideal | 17:47 |
| sdague | which would publish out on merge | 17:47 |
| sdague | etoews: I think it's a fine bar to set here | 17:48 |
| * etoews reigns in skepticism | 17:48 | |
| elmiko | hehe | 17:48 |
| sdague | etoews: why are you skeptical? | 17:48 |
| etoews | okay | 17:48 |
| etoews | sdague: do you envision the docs tree being in the same code base as the the code where the error is being propagated from? | 17:50 |
| sdague | etoews: yes | 17:50 |
| sdague | much like the api docs are all migrating back to the projects | 17:50 |
| etoews | that's mostly where my skepticism comes from | 17:51 |
| sdague | etoews: that projects won't do that? | 17:51 |
| etoews | if they were separate code bases, it's just much less likely to happen. | 17:51 |
| sdague | right, I agree, this doesn't work if they are separate code bases | 17:52 |
| sdague | but, the way I'd imagine this structurally in the nova tree, every exception class gets an error code attached to it. We have a part of the docs tree that describes that in more in depth (or possibly docstrings on the exceptions) | 17:53 |
| sdague | then in the code it's one exception type per narrow error code | 17:53 |
| sdague | and docs to publish at the same time | 17:53 |
| etoews | that seems like a reasonable path forward | 17:54 |
| etoews | but something i do *not* want this guideline to do is mandate the creation of those errors in a doc tree. | 17:54 |
| etoews | that's a per project thing or maybe even a cross-project thing | 17:54 |
| elmiko | etoews: | 17:55 |
| elmiko | +1, guideline should stick to api matters | 17:55 |
| sdague | so, it seems a little pointless not to mandate that here, because without the context of how this is useful as a whole, I think it's impact is much less. | 17:59 |
| sdague | the point of having an API WG is to increase usability of the API across openstack | 17:59 |
| sdague | if only the narrowest definition is embraced, then there are lots of gaps where someone assumes it's someone else's problem, but no one fills in | 18:00 |
| *** lucasagomes is now known as lucas-afk | 18:01 | |
| elmiko | the whole point about suggesting doc creation for the errors just seems a little out of scope for the api-wg | 18:02 |
| elmiko | i agree though that it does improve the openstack ecosystem if people follow that model though | 18:02 |
| etoews | it also becomes a barrier to adopting the error guideline | 18:02 |
| etoews | i'm all for the creation of such error docs | 18:02 |
| sdague | etoews: yes, a barrier which we specifically want | 18:02 |
| etoews | but i think it's much more suited to a cross-project spec rather than a sentence or two in an api guideline. | 18:03 |
| sdague | etoews: that seems like punting on the point of the working group. This is a cross project effort. | 18:04 |
| sdague | I consider anyone adopting the error spec without the documentation and claiming victory as a failure of the spec. Without the documentation it's not a thing. It's just random strings people have to go read source code to figure out. | 18:05 |
| etoews | we have an established scope for the api wg. this certainly seems to be outside of it. the scope of the cross project wg fits perfectly for this. | 18:06 |
| sdague | there is no cross project wg | 18:06 |
| sdague | that's not a thing | 18:06 |
| sdague | there are cross project working groups, like the api-wg | 18:06 |
| etoews | remind me where the cross-project specs live? | 18:07 |
| elmiko | but if we advocate for the error doc changes, wouldn't we need to expand the guideline to cover how those docs should be created? | 18:07 |
| sdague | elmiko: yes, which I think is critically important | 18:07 |
| etoews | http://specs.openstack.org/openstack/openstack-specs/ | 18:07 |
| sdague | because if that doesn't exist from day one, then this is going to be no less of a mess than the current one | 18:07 |
| sdague | etoews: yes, which is the TC stamping things that need overall agreement and don't fit into existing cross project working groups that have been spun out | 18:08 |
| elmiko | i agree on principle, i'm just trying to wrap my head around the api-wg getting more into pusing the boundaries of doc stuff. i suppose we kinda do this with respect to how apis should be documented. | 18:08 |
| sdague | yeh, and because from a standpoint of a more usable API, it's a huge part of the problem space | 18:09 |
| etoews | ah. given the title "OpenStack Cross-Project Specifications and Policies" i was under the impression that a wg was responsible for putting those together. | 18:10 |
| sdague | no, that's kind of fallback of stuff that doesn't fit anywhere else | 18:10 |
| sdague | anyway, need to grab lunch, but I really really think we should have the docs story part of the error spec, because it's important to get right, and if it's not in there, it's going to be done half a dozen different ways by projects, and the hoped for consistency will be lost | 18:12 |
| elmiko | is it acceptable to specify that the error docs need to get published, but not get into the implementation details of how they should be published? (being a little more agnostic about the methodology) | 18:13 |
| etoews | sdague: okay. i simply don't have a good vision for how these errors docs will play out. would you be willing to add commits to the patch set or handle it in a follow on PR? | 18:14 |
| etoews | it sounds like it would require extensive explanation and one or more sections in https://review.openstack.org/#/c/167793/7/guidelines/errors.rst | 18:15 |
| *** alex_xu has quit IRC | 18:56 | |
| *** alex_xu has joined #openstack-api | 18:57 | |
| *** e0ne has joined #openstack-api | 19:00 | |
| *** e0ne has quit IRC | 19:10 | |
| *** yunpengli has joined #openstack-api | 19:10 | |
| *** e0ne has joined #openstack-api | 19:10 | |
| *** e0ne has quit IRC | 19:27 | |
| *** yunpengli has quit IRC | 19:43 | |
| *** annegentle has quit IRC | 19:45 | |
| *** annegentle has joined #openstack-api | 20:13 | |
| *** fzdarsky has quit IRC | 20:17 | |
| *** nikhil_k has quit IRC | 20:54 | |
| *** alex_klimov has joined #openstack-api | 20:56 | |
| *** subscope has joined #openstack-api | 21:16 | |
| *** jaypipes has quit IRC | 21:49 | |
| *** salv-orlando has joined #openstack-api | 21:51 | |
| *** salv-orlando has quit IRC | 22:05 | |
| *** nikhil has joined #openstack-api | 22:27 | |
| *** alex_klimov has quit IRC | 22:53 | |
| *** subscope has quit IRC | 23:26 | |
Generated by irclog2html.py 2.14.0 by Marius Gedminas - find it at mg.pov.lt!