[doc] installation guide maintenance

Stephen Finucane stephenfin at redhat.com
Mon Jun 8 11:36:16 UTC 2020

On Thu, 2020-06-04 at 18:40 +0900, Akihiro Motoki wrote:
> Hi,
> During the doc migration, the installation guide was moved to
> individual project repos.
> I see problems in installation guide maintenance after the migration.
> - The installation guide is not maintained well perhaps in many projects.
>   AFAIK they are not verified well at least in horizon and neutron.
> - Even if we try to verify it, it is a tough thing because we need to
> prepare base distribution
>   and setup other projects together (of course it depends on projects).
>   This leads to a development bandwidth and priority issue.
> - We sometimes receive bug reports on the installation guide, but it
> is not easy for the
>   upstream team confirm them and verify fixes.
> I guess the installation guides are not being maintained well from
> these reasons.
> Any thoughts on this situation? (This is my first question.)

As has been summarized above and elsewhere, this is almost certainly a
bandwidth and priority issue.

> If a project team has no bandwidth to maintain it, what is a recommended way?
> I see several options:
> - Drop the installation guide (per OS or as a whole) -- If drop what
> should the criteria be?
> - Keep the installation guide with warnings like "the upstream team
> does not maintain it and just host it".
> - Keep it as-is (unmaintained)

Personally, I'd love to see per-cycle hackathons where people sit down
and install an OpenStack deployment manually on each OS, however, I
can't see that happening and most teams have no interest in setting
aside time each cycle to validate this themselves. The latter point is
unfortunate, since the process of doing such manual work often serves
to highlight the uglier corners of project configuration, but it is
also understandable since this work is often tedious and unrewarding.

As you've mentioned below, most (all?) people using OpenStack for
anything more than a learning tool are installing using a deployment
tool. I personally suspect the amount of people using OpenStack on
CentOS/RHEL without TripleO/Director or something like Kolla is
exceedingly low, bordering on non-existent. Similarly, I would assume
the Ubuntu users are using a combo of MAAS/Juju while the amount of
people installing OpenStack on SUSE with anyting is likely approaching
zero now, given their divestment. All in all, while I'd rather we
didn't have to do so, I think deleting the installation guides is
probably the right move. It sucks and will result in a worse experience
for our users, but it's just a reflection of reality.

Thanks for bringing this up,

> Finally, I am not sure we need to maintain step-by-step guides on
> installations and
> I wonder we need to drop them at some time.
> Most users deploy OpenStack using deployment projects (or their own
> deployment tools).
> Step-by-step guides might be useful from educational perspective
> but unmaintained guides are not useful.
> Thanks in advance,
> -- Akihiro Motoki (amotoki)

More information about the openstack-discuss mailing list