osdir.com


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[doc] installation guide maintenance


I just ran through an install last week and found 3 issues. One was a bad
link which I put a patch up for, the other there was a Horizon bug for, and
the last was Placement and I've reached out in #openstack-placement but
need to follow up I'm willing to patch the docs but not sure where as
there's 2 options. I only did Keystone, Nova, Glance, Neutron, Placement,
and Cinder so not sure the state of any others

Thanks,

Amy (spotz)

On Thu, Jun 4, 2020 at 9:11 AM Jeremy Stanley <fungi at yuggoth.org> wrote:

> On 2020-06-04 18:40:45 +0900 (+0900), Akihiro Motoki wrote:
> > 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.)
> [...]
>
> This could be an ambitious proposal, but the way the Zuul community
> has approached the problem is that it has a CI job which mirrors its
> "quick start" deployment guide, with a review policy and embedded
> comments indicating that any time one is changed the other must also
> be changed to match. In essence, run automatic tests of the exact
> same steps you're documenting, or as many of them as you possibly
> can at least, and keep the two in sync.
>
> Since its inception, OpenStack has been distinguished by how its
> approach to automated testing is superior to the obsolete practice
> of a human sitting in front of a computer manually trying the same
> sets of documented steps over and over... which is exactly how the
> installation guides were still being tested (or more to the point,
> why they've not been tested with any real consistency for years).
> --
> Jeremy Stanley
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200604/d4dcbf8d/attachment.html>