Open Stack

Dragging this thread back up from the depths as I've updated the
governance patch as of this morning: https://review.opendev.org/#/c/657
142/

On Mon, 2019-08-19 at 14:16 -0400, Doug Hellmann wrote:
> > On Aug 19, 2019, at 1:56 PM, Jeremy Stanley <fungi at yuggoth.org>
> > wrote:
> > 
> > On 2019-08-19 12:49:41 -0500 (-0500), Sean McGinnis wrote:
> > [...]
> > > there seems to be a big difference between owning the task of
> > > configuring the site for the next release (which totally makes
> > > sense as a release team task) and owning the entire
> > > docs.openstack.org site.
> > 
> > That's why I also requested clarification in my earlier message on
> > this thread. The vast majority of the content hosted under
> > https://docs.openstack.org/ is maintained in a distributed fashion
> > by the various teams writing documentation in their respective
> > projects. The hosting (configuration apart from .htaccess files,
> > storage, DNS, and so on) is handled by Infra/OpenDev folks. If it's
> > *just* the stuff inside the "www" tree in the openstack-manuals
> > repo
> > then that's not a lot, but it's also possible what the release team
> > actually needs to touch in there could be successfully scaled back
> > even more (with the caveat that I haven't looked through it in
> > detail).
> > -- 
> > Jeremy Stanley
> 
> 
> The suggestion is for the release team to take over the site
> generator
> for docs.openstack.org (the stuff under “www” in the current
> openstack-manuals git repository) and for the SIG to own anything
> that looks remotely like “content”. There isn’t much of that left
> anyway,
> now that most of it is in the project repositories.

I like this.

> 
> Most of what is under www is series-specific templates and data files
> that tell the site generator how to insert links to parts of the
> project documentation in the right places (the “install guides” page
> links
> to /foo/$series/install/ for example). They’re very simple, very
> dumb, 
> templates, driven with a little custom script that wraps jinja2, 
> feeding the right data to the right templates based on series name.
> There is pretty good documentation for how to use it in the
> tools [1] and release [2] sections of the docs contributor guide.
> 
> The current site-generator definitely could be simpler, especially
> if it only linked to the master docs and *those* linked to the older
> versions of themselves (so /nova/latest/ had a link that pointed to
> /nova/ocata/ somewhere). That would take some work, though.
> 
> The simplest thing we could do is just make the release team
> committers
> on openstack-manuals, leave everything else as it is, and exercise
> trust between the two groups. If we absolutely want to separate the
> builds,
> then we could make a new repo with just the template-driven pages
> under “www”,
> but that’s going to involve changing/creating several publishing
> jobs.

I think this is a suitable option. I would like the docs team cores to
review this, and approve. But I think this is the best/simpliest option
for now. 

-- 
Alexandra Settle <a.settle at outlook.com>
IRC: asettle