| Posted | Nick | Remark | |
|---|---|---|---|
| #openstack-sdks - 2019-08-29 | |||
| 16:08:15 | elmiko | i'm not sure what to do about the todos | |
| 16:08:18 | gtema_ | really? | |
| 16:08:25 | dtantsur | (I'm in DUS starting next week, so do your math!) | |
| 16:08:56 | gtema_ | I am not in DUS, was there already 2 times last week and not willing to go again - too crowded | |
| 16:09:00 | elmiko | i wonder if we could replace the todos with some specific language about there not being any guidance yet? is that any better than just a "todo" | |
| 16:09:09 | gtema_ | but I am on DOST in Sept in Berlin. Are you there? | |
| 16:09:29 | dtantsur | gtema_: in in Dusseldorf the whole September probably | |
| 16:09:42 | gtema_ | beh | |
| 16:09:42 | dtantsur | anybody going to OpenInfra Nordics? | |
| 16:09:55 | gtema_ | beh was not to Nordics | |
| 16:10:16 | dtantsur | I may end up here mid-September, depending on various circumstances | |
| 16:10:20 | gtema_ | I'm not - only "Deutsche OpenStack Tage" | |
| 16:10:33 | dtantsur | but my primary goal is to find a flat in DUS asap | |
| 16:10:52 | elmiko | ooh, nice dtantsur ! | |
| 16:10:56 | gtema_ | coool | |
| 16:11:57 | dtantsur | elmiko: I suggest we file a bug per each TODO and then follow the same process | |
| 16:12:05 | dtantsur | fix it OR close and remove the todo | |
| 16:12:28 | elmiko | i feel like that is where we are stuck though, the "fix it or forget it" stage | |
| 16:12:48 | elmiko | but, i like the idea of making some bugs to track this better | |
| 16:12:58 | elmiko | well, maybe not better, but just not in the docs themselves | |
| 16:13:20 | dtantsur | yeah | |
| 16:13:49 | gtema_ | ++ | |
| 16:14:52 | elmiko | so, it's a long holiday weekend here in the states, but i will make some actions next week when i return | |
| 16:15:03 | gtema_ | Guys, what do you think about API header “Accept: “? It does not make any sense from my POV and due to some patch/API Gateways in front some of the requests to Swift in my cloud are failing. | |
| 16:15:20 | efried | merge enormous doc patches, even though they're known to be incomplete, as long as they're at least largely technically accurate. open bugs for known gaps therein. | |
| 16:15:54 | dtantsur | gtema_: in what context? in some contexts it does make sense | |
| 16:16:04 | dtantsur | efried: ++ that's what we're discussing | |
| 16:16:07 | gtema_ | i.e. HEAD request | |
| 16:16:09 | elmiko | efried: my concern here is removing the "TODO" language from the docs and migrating that into bugs | |
| 16:16:48 | efried | I like the idea of keeping TODOs in docs, because they're more likely to be noticed by people consuming the docs, and more noticed is more likely to be acted upon. | |
| 16:16:48 | gtema_ | currently in SDK we enforce "Accept: " for head requests and for create object | |
| 16:16:51 | elmiko | efried: ahh, i see though, you are saying we should push through some of these long standing doc patchs? | |
| 16:17:00 | efried | yes elmiko, this ^ | |
| 16:17:14 | efried | They're stagnant because they're so huge that nobody wants to review them. | |
| 16:17:18 | elmiko | my only problem with that notion is that they have been there for a long time and no one has acted on them | |
| 16:17:24 | dtantsur | I'm not convinced anybody will ever fix TODOs that we don't fix | |
| 16:17:27 | elmiko | the todos that is | |
| 16:17:32 | elmiko | dtantsur: ++ | |
| 16:17:40 | efried | that doesn't mean we should get rid of them | |
| 16:17:47 | efried | that would be like denying that the gaps exist. | |
| 16:17:52 | dtantsur | gtema_: sending Accept without expecting a body is certainly weird | |
| 16:18:02 | efried | If nobody cares about the gaps, then indeed nobody will close them. But that doesn't mean they don't exist. | |
| 16:18:05 | elmiko | i would prefer changing the language from "TODO" to something more reflective of our actual position though. | |
| 16:18:30 | dtantsur | yeah, maybe we should change the syntax to something more user-friendly and saying "The API SIG doesn't currently have a guidance on ..." | |
| 16:18:34 | elmiko | right | |
| 16:18:54 | elmiko | at least let folks know that we have been unable to agree on, or generate guidance for those todos | |
| 16:19:03 | dtantsur | a raw TODO in text may give an impression that we're working on it | |
| 16:19:06 | dtantsur | while we're not working :) | |
| 16:19:09 | elmiko | "todo" sounds like we might actually get around to it | |
| 16:19:15 | elmiko | dtantsur: yes! | |
| 16:19:21 | dtantsur | elmiko: are you reading my thoughts??? | |
| 16:19:25 | elmiko | hahaha | |
| 16:19:28 | gtema_ | dtantsur: that's what we do. But it is something more general, that from the API pov there are no real guidance | |
| 16:19:36 | efried | .. help-wanted:: | |
| 16:19:36 | efried | Consider a new | |
| 16:19:36 | efried | role | |
| 16:19:47 | elmiko | that's a nice thought efried | |
| 16:19:49 | dtantsur | that would be ideal | |
| 16:19:59 | efried | stephenfin could work that up for us in all his spare time. | |
| 16:20:05 | edleafe | elmiko: "todo" sounds like there is a plan to actually get around to it :) | |
| 16:20:16 | gtema_ | agree | |
| 16:20:18 | elmiko | edleafe: exactly, i want to be more transparent | |
| 16:20:34 | elmiko | efried: i would be happy with a "help wanted" plus changing the todo language to something more honest | |
| 16:21:05 | elmiko | well, more reflective of our actual intentions | |
| 16:21:23 | dtantsur | and maybe some rough ideas on what a guidelines could look like | |
| 16:21:29 | efried | I didn't want to get into this on the ML, but I don't like the idea that "if nobody is asking it must not be important". | |
| 16:21:31 | stephenfin | efried: | |
| 16:21:33 | stephenfin | .. admonition:: Help wanted | |
| 16:21:34 | stephenfin | ||
| 16:21:34 | dtantsur | "We don't know for sure, but something in spirit of RFC XYZ" | |
| 16:21:38 | dtantsur | yeah | |
| 16:21:38 | stephenfin | Stuff. | |
| 16:21:46 | stephenfin | QED | |
| 16:21:54 | elmiko | efried: ++, that's a good thought to capture | |
| 16:21:57 | efried | stephenfin: cool, I had a feeling there might be something existing that would work. | |
| 16:22:10 | elmiko | they _are_ important, but we have failed as a sig to arrive at any guidance on those topics | |
| 16:22:12 | dtantsur | tripleo-docs uses admonitions quite actively, we can check how they do it | |
| 16:22:23 | elmiko | dtantsur: ++ | |
| 16:22:24 | efried | All too often people just give up because it's too hard or time consuming or soul-sucking to continue complaining about stuff that's been TODO f'rever. | |
| 16:22:51 | dtantsur | if we had one person per each big project.. cough-cough | |
| 16:23:10 | dtantsur | :D | |
| 16:23:16 | elmiko | haha | |
| 16:23:20 | efried | It's just that we're all stretched so thin | |
| 16:23:24 | dtantsur | indeed | |
| 16:23:26 | elmiko | yyup | |
| 16:23:36 | efried | unfortunately docs always end up being a thing that suffers, falls off the bottom. | |
| 16:23:48 | dtantsur | yep. and dev docs is the least liked kind of docs | |
| 16:23:54 | elmiko | i feel like even migrating from TODO to "we could use help here but have no guidance currently" is at least more reflective of where we are at | |
| 16:24:04 | edleafe | So like elmiko said, let's be transparent about that | |
| 16:24:08 | dtantsur | very much agreed | |
| 16:24:17 | gtema_ | ++ | |
| 16:24:34 | efried | so anyway, the path of least resistance but biggest effect IMO is to keep the TODOs (with help-wanted admonition makeover if desired) and keep them in front of people's faces (i.e. keep them in the docs). | |
| 16:24:41 | elmiko | cool, i have _some_ time (he said sheepishly), i'll take the lead on geting something moving | |
| 16:25:08 | elmiko | efried: ack, we won't take them out but i would really like to make them more explicit | |
| 16:25:08 | dtantsur | elmiko++ | |
| 16:25:10 | efried | we are all in violent agreement | |
| 16:25:27 | elmiko | we can argue about the details on review ;) | |
| 16:25:40 | dtantsur | oh we can :) | |
| 16:25:41 | efried | also, consider merging the massive-doc-patches as is and refacing the TODOs in subsequent patches. | |
| 16:25:43 | elmiko | haha | |