Posted	Nick	Remark
#openstack-sdks - 2019-10-28
14:15:26	openstackgerrit	Riccardo Pittau proposed openstack/openstacksdk master: Add reset_interfaces argument to patch_node https://review.opendev.org/689414
14:18:34	openstackgerrit	Riccardo Pittau proposed openstack/openstacksdk master: Increase dogpile version for Py3.7 compatibility https://review.opendev.org/691680
14:58:51	openstackgerrit	Marc Gariépy (mgariepy) proposed openstack/python-openstackclient master: [DOC]Fix openstack command for removing router https://review.opendev.org/691375
16:18:06	efried	dtroyer: So as I'm working through these plugin docs issues, it has been in the back of my head:
16:18:34	efried	Should the plugin projects build osc in a gate job, so they don't break it?
16:18:57	efried	or maybe they already do, /me looks...
16:20:12	efried	ah, I guess that's what openstackclient-plugin-jobs would be for? ...
16:22:01	efried	ugh, that guy doesn't require novaclient or osc-placement.
16:22:22	efried	also, it doesn't appear to build docs, which would be a useful add.
16:22:52	efried	...and it's marked as non-voting by default.
16:27:22	efried	...and the only thing it does right now is check for duplicate entry points.
16:27:38	efried	okay, so tldr some of the infrastructure is there, but it hasn't really been fleshed out.
16:28:12	dtroyer	efried: exactly. that was all supposed to come together in the openstackclient repo and never did
16:28:46	dtroyer	IIRC stevemar was organizing all of that when IBM lured him to the dark side…
16:29:02	efried	dtroyer: those IBM guys...
16:29:17	efried	dtroyer: so what's next here?
16:30:24	efried	like, if I want to do a thing (like make sure python-xclient doesn't break python-openstackclient's doc build with a bogus option help) it would be nice if I didn't have to drag that entire openstackclient infra effort into daylight first.
16:30:39	dtroyer	efried: I think the cross-project plugin stuff still belongs in openstackclient, its purpose is to provide that integration for users, makes sense for the knowledge of plugins to all be there.
16:30:50	efried	put another way: I'd like to be able to contribute without signing up for fixing the world.
16:30:55	dtroyer	exactly, which is why I'm not insisting that it be moved before improving what we do have
16:31:17	dtroyer	just keep that in mind so we don't break that possibility somehow
16:31:43	efried	okay, so...
16:32:05	efried	I'm not actually going to be able to use that openstackclient job, since that project isn't building plugin docs yet
16:32:25	efried	so I would need to need to create a new job in python-openstackclient
16:32:55	efried	...that installs all the plugins and builds its docs.
16:33:08	efried	well
16:33:21	efried	I guess I'll ask you: of those two alternatives, which seems like the path of least resistance?
16:33:38	dtroyer	I don't really like that either… and this is all one reason I wasn't involved in it in the first place, I didn't want osc to be an integration bottleneck
16:34:47	efried	mm, especially if the goal is to add $job to each of the 20+ plugin client projects, it would be better for it to be the real, long-term-plan job.
16:35:49	efried	dtroyer: so was the eventual goal to somehow have the osc doc build moved from python-openstackclient to openstackclient?
16:36:07	dtroyer	if there is a lot to build, let's just do it in the final place.
16:36:37	dtroyer	There was never a final goal to have a single doc, maybe a single index pointing to the individual ones, but the OSc dosc themselves should only cover what is in the repo
16:37:02	efried	well...
16:37:08	dtroyer	the whole point of plugins was supposed to be freedom (for OSC) from having to gatekeep any of this
16:37:13	efried	not sure I agree with that from a UX standpoint.
16:37:24	efried	I mean, I understand from a project management perspective.
16:38:05	efried	but as a consumer of the docs, I would like to be able to navigate around the plugin docs without having to use the browser's Back button liberally.
16:38:14	efried	Guess that's not the end of the world.
16:38:27	dtroyer	when there is less than a single half-time person maintaining something, this is what you get. If someone has the time to build an integrated all plugins-and-everything doc, go for it. I don't have that luxury any more.
16:38:43	efried	well, that's what I've done.
16:39:52	efried	https://docs.openstack.org/python-openstackclient/latest/cli/plugin-commands/index.html <== all of these links point to in-repo (python-openstackclient) docs built via autoprogram-cliff of the registered entrypoints of the plugins.
16:40:02	dtroyer	ok, cool. I'll suggest that openstacklcient is the right repo for osc+plugins stuff,
16:40:15	dtroyer	yup, that was intended to be moved
16:40:29	efried	(all but the last five, which just need https://review.opendev.org/#/c/690387/ which is waiting for three final u-c bumps)
16:40:54	efried	And should the rest of the python-openstackclient documentation also be moved?
16:41:07	dtroyer	no, unless you would do that for all of the plugins too.
16:41:19	efried	sorry, "do that" what?
16:41:24	dtroyer	move all of their docs
16:41:37	dtroyer	python-openstackclient as functioanlity and docs for that in one place
16:41:39	efried	well, the docs at $plugin are a separate thing.
16:41:54	dtroyer	and openstackclient is the integration point, not python-openstackclient
16:42:40	dtroyer	this is such a mess because that transition was not completed and isn't a high enough priority (until now) for anyone to spend time on it
16:44:10	dtroyer	this is life in a project that nobody really wants to pay for… "clients are not important" — a (former) OSF Platinum Board Member
16:44:49	efried	okay, it's not a super high priority, I just came across it because I was trying to get at some plugin docs and couldn't find them in the first few obvious places I looked. What exists now is a dramatic improvement, but it's brittle.
16:45:06	efried	Before, $plugin could merge a broken option help and nobody would be the wiser
16:45:18	efried	like, literally nobody, because those weren't being used *anywhere* afaict.
16:45:27	efried	Not even sure if they were being used to build the CLI helps. Maybe they were...
16:45:41	efried	but those obv don't have the same rules as the sphinx-built docs.
16:46:15	efried	anyway, now if $plugin merges and releases a bogus option help, python-openstackclient will start to fail its doc build.
16:46:29	efried	so it would be nice to prevent that rather than having to go fix it after the fact.
16:46:48	efried	esp because the rate of change in python-openstackclient is so low, it could be ages before anyone even notices the breakage.
16:47:15	dtroyer	again, this is why I did not want to be in the integration business
16:47:46	efried	understood
16:47:48	dtroyer	at least not in the python-openstackclient repo
16:48:16	efried	can you just bear with me a little bit longer and help me understand what the ideal utopian future state of this openstackclient repo would be?
16:49:08	efried	and then I'll just take the ball and run it wherever I think will get us closer, if probably not actually all the way there.
16:50:49	dtroyer	sure: anything and everything that should be handled across all (self-identified) plugins and OSC itself should happen there… docs, co-installability testing, whatever. Even registering their existence. Definition of the jobs so plugins (and OSC) can run the jobs to do the checking as those projects decide they care. This is meant to be opt-in, as I don't enforce the OSC command structure standards on plugins (I lost that argument too), we'll t
16:53:58	openstackgerrit	Riccardo Pittau proposed openstack/openstacksdk master: Add reset_interfaces argument to patch_node https://review.opendev.org/689414
17:06:04	efried	dtroyer: before I go asking the docs folks, any idea why openstackclient docs aren't being published? I see a doc/ dir with appropriate requirements, config, and an index.rst; and the .zuul.yaml lists the build-openstack-docs-pti template
17:07:38	dtroyer	efried: it may have never been set up, that repo wasn't really used until I released OSC 4 a couple of months ago
17:37:39	openstackgerrit	Eric Fried proposed openstack/openstackclient master: Update doc index links (for storyboard etc) https://review.opendev.org/691728
17:38:35	efried	dtroyer: I'm gonna see if this builds docs at least in zuul. If it does, I think I'm going to copy all (or most?) of the docs from python-openstackclient into it. Then I can beef up that zuul job to build docs as well as do that dup check. Then I can start spraying that job into all the plugin projects.
17:39:17	efried	even if the docs never get published, that job running in zuul will allow us to gate and detect future option help breakages.
17:40:08	dtroyer	efried: ok, thanks for spending time on this
17:40:17	efried	eventually if the docs do get published, we can stuff redirects in python-openstackclient, but we would probably still want *some* of the docs available there, so I'm not going to get real excited about that yet. Problem for future-us.
17:40:29	efried	yahyoubetcha.
17:43:42	efried	...seems to have worked fine
17:50:56	efried	okay, it's not publishing because it's using the build-...-pti job, not the publish-...-pti job.
17:50:56	efried	...which actually could be useful for our purposes here. Means I could make the docs build gate plugin projects without actually having to worry about whether the docs are pretty or correct.
17:51:29	efried	dtroyer: that said, if you *do* want to start publishing those, it would be trivial at this point. Do you want me to pull that trigger?
18:29:52	openstackgerrit	Merged openstack/openstacksdk master: Switch to Ussuri jobs https://review.opendev.org/691158
19:26:31	dtroyer	efried: I'm not sure I want to publish docs outside of where they are maintained. ie, a single consolidated doc requires someone to curate it and I'm not signing up for that. I understand the ux sux but adding anything beyond pointers to the individual pieces eventually makes a worse experience when it gets stale
19:27:02	dtroyer	I've always found bad docs more frustrating than no docs FWIW
19:27:05	efried	dtroyer: that's not really the question at the moment.
19:27:47	dtroyer	than I'm misunderstanding it
19:27:48	efried	Maybe I misunderstood, but I thought the eventual goal was to maintain the osc docs in the openstackclient project, not python-openstackclient.
19:28:06	efried	this would be a step in that direction, though not getting us all the way there yet.
19:28:18	efried	do you mean maintaining docs outside of where the corresponding code is maintained?
19:28:27	dtroyer	no, the OSC docs belong with the code, just like the plugin docs
19:28:58	dtroyer	a unified guide of some sort would be great, but that's what we don't have the capacity to do, very similar to the overall docs efforts
19:31:53	efried	okay, so here's my current strategy:
19:31:53	efried	- Copy the python-openstackclient docs to the openstackclient project. Keep the build-...-pti, don't publish yet.
19:31:53	efried	- Beef up the openstackclient-plugin-jobs template to include building those docs ^.
19:31:53	efried	- Make sure all the plugin projects gate on openstack-plugin-jobs. This prevents them from merging patches with broken option helps.
19:32:37	dtroyer	I don't want to move docs from python-openstackclient to openstackclient
19:33:06	dtroyer	unless they are bits talking about the entire collection of things. leave the individual command stuff with the commands
19:33:46	efried	Right.
19:33:47	efried	The next (future, I'm not planning on doing this any time soon) steps would be:
19:33:47	efried	- Scrub the docs in both projects to keep the appropriate ones in the appropriate project. Add redirects from any python-openstackclient ones we remove. (No redirects from openstackclient are necessary because never published.)
19:33:47	efried	- Start publishing openstackclient docs.

Earlier   Later