| Posted | Nick | Remark | |
|---|---|---|---|
| #openstack-sdks - 2019-08-29 | |||
| 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 | |
| 16:26:09 | dtantsur | efried: also true. especially with the version discovery monster. | |
| 16:26:11 | gtema_ | oj, the nitpicker of dtantsur is a killer bomb ;-) | |
| 16:26:12 | efried | because there's a mental barrier to re-reviewing a 1KLOC patch. | |
| 16:26:17 | elmiko | efried: yes, i will make notes about this when i triage next week. if those patches are in good enough shape to merge i will weigh that heavily in my comments. | |
| 16:26:19 | efried | regardless of how small the inter-patch delta is. | |
| 16:26:35 | elmiko | efried: ++ | |
| 16:27:29 | efried | especially with docs, as long as the patch moves the ball forward and doesn't introduce actual inaccuracies, we should be able to be much less perfectionist about merging | |
| 16:27:46 | efried | it's not like we're going to introduce a security regression or something. | |
| 16:27:51 | elmiko | yeah | |
| 16:27:53 | efried | break CERN's deployment. | |
| 16:28:03 | elmiko | i think we've just been really nitpicky about getting the details correct | |
| 16:28:13 | elmiko | and that version discovery beast is tough to wrangle | |
| 16:28:18 | efried | no joke | |
| 16:28:45 | elmiko | especially when we stay true to our processes and ask for input from the community | |
| 16:29:48 | elmiko | efried: so that's a question i have though. we have clear guides about how we will merge changes, i don't think it's a good idea to break them /but/ we do open ourselves up to drive by -1's when we do this and that throws the whole process off. any suggestions? | |
| 16:30:39 | efried | clear guides written for different times; we should have the temerity to alter those processes. | |
| 16:30:48 | elmiko | fair | |
| 16:31:10 | dtantsur | ++ | |
| 16:31:34 | efried | A number of teams are, out of necessity, moving to single-core approvals. Not saying thats' a good idea here necessarily, just that it's a thing. | |
| 16:31:36 | elmiko | appreciate all the feedback, it is helpful | |
| 16:31:37 | dtantsur | and the version discovery one doesn't have -1's | |
| 16:31:48 | elmiko | dtantsur: ++ | |
| 16:31:50 | dtantsur | so strictly speaking we can approve it | |
| 16:31:59 | elmiko | cool, maybe we just do that | |
| 16:32:16 | elmiko | give it one more read through to make sure there are not glaring errors | |
| 16:32:25 | efried | Yeah, for something like this, if it's clear it's been thoroughly reviewed by people with at least some understanding of the content, it's reasonable to proxy their +1 as a +2 when there's a dearth of cores available. | |
| 16:32:27 | efried | IMHO | |
| 16:32:35 | elmiko | ++ | |