Open Stack

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 --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200604/8df9584c/attachment.sig>