Open Stack

Excerpts from Matt Kassawara's message of 2016-04-01 12:38:02 -0600:
> Hi,
> 
> I didn't see this e-mail until now because I'm busy trying to update and
> test the installation guide in time for the Mitaka release. As a primary
> contributor to the installation guide for about six releases including
> restructuring it a couple of times, I think I can explain why we do what we
> do.
> 
> First, a little history about the guide...
> 
> The installation guide often provides the first experience for people
> trying OpenStack. Thus, the guide should provide not just a good
> experience, but a great experience. We can all agree on wanting more
> adoption of OpenStack. For many people, launching an instance and being
> able to access it feels like summiting a mountain. My first experience with
> OpenStack involved nearly a month of trying to install Grizzly with neutron
> for evaluation purposes using the installation guide. It didn't work.
> Looking at various support channels such as IRC and ask.openstack.org, most
> people were stuck at the same place without any answers. I finally
> determined that nova lacked the configuration telling it to use neutron for
> networking, so it kept attempting to build nova networks when those
> components didn't exist. I opened a bug and someone fixed it. Shortly
> thereafter, I began addressing the seemingly infinite number of
> installation guide bugs. However, the cycle of frustration was beginning to
> repeat itself with Havana. The reactive method of finding a problem,
> opening a bug, and waiting for a patch simply wasn't working for our
> audience of potential operators, not developers, that just expect it to
> work.
> 
> So, I proposed changing the guide from reactive to proactive. In other
> words, we update and test the guide prior to release for every distribution
> it supports. We began this approach with Icehouse and saw a decrease in
> bugs and frustration. Furthermore, when assisting people through various
> support channels, we could more easily determine whether the problem was a
> just a typo or a problem with the guide. However, proactively maintaining
> the guide put a significant burden on the contributors. Gone were the days
> of "fire-and-forget" patches. Almost all patches require actual testing,
> sometimes across several distributions. Updating the guide for the next
> release requires performing full installations, often several times per
> distribution, until we can successfully install and test all services
> without deviating from the instructions. A considerable amount of work,
> especially about a month before release when contributors who involve
> themselves in other projects are also busy trying to release those
> projects. Thus, the installation guide has seen a decrease in contributions
> making it increasingly difficult to update and test for each release.
> Furthermore, the installation guide receives little, if any, support from
> most projects including "core" projects. Even if those projects know about
> the installation guide, most assume that the documentation team magically
> updates it for every release to deploy each service in a basic fashion
> accounting for configuration changes and recommendations. From the
> perspective of a project developer, those updates probably seem simple.
> Just read the code, track patches, and maybe attend some meetings, right?
> From the perspective of installation guide contributors, we can't involve
> ourselves that deeply in one project let alone nearly ten projects. Imagine
> us trying to consider big tent projects? We have begged projects for years
> to provide resources for maintaining the installation guide. If nothing
> else, provide some notes on an etherpad indicating what we should change.
> At this point in the game, we shouldn't have to resort to deprecation
> messages or gate job configurations to determine how to deploy a service.
> 
> Regarding use of distribution packages instead of source...
> 
> The guide uses distribution packages instead of source because our audience
> is usually familiar with them and they eliminate a significant number of
> steps in an already complex and often overwhelming process. For example,
> packages manage dependencies and provide init scripts. The installation
> guide teaches our audience how to deploy the most common OpenStack services
> for evaluation purposes. For example, our audience quickly learns that each
> service typically depends on keystone, a database, and a message queue.
> After getting comfortable with the installation process, we recommend
> implementing redundancy/security on top of a basic installation and
> eventually tooling for a production deployment.
> 
> Distribution packages aren't perfect by any means. First, they usually lag
> the upstream release cycle by several weeks which forces us to update and
> test changes using milestones, sometimes not even the last "feature-freeze"
> milestone, after the first release candidate appears upstream. Next, they
> sometimes contain bugs and packagers seldom contribute resources to triage
> and address them which forces us to implement workarounds that can confuse
> or distract our audience. Finally, and most importantly, we can only
> include a project in the installation guide if all distributions provide
> packages for it which prevents us from adding many newer projects and just
> about anything in the big tent.
> 
> We would love to add all sufficiently mature projects to the installation
> guide because it increases visibility and adoption by operators, but we
> lack resources to develop a source installation mechanism that retains as
> much simplicity as possible for our audience.

I think it would be a big mistake to try to create one guide for
installing all OpenStack projects. As you say, testing what we have
now is already a monumental task and impedes your ability to make
changes.  Adding more projects, with ever more dependencies and
configuration issues to the work the same team is doing would bury
the current documentation team. So I think focusing on the DefCore
list, or even a smaller list of projects with tight installation
integration requirements, makes sense for the team currently producing
the installation guide.

One effect of the Big Tent change in governance was supposed to be
that cross-project teams changed from producing content to enabling
others to produce content.  With that in mind, instead of adding
everything to one manual, I think we should be enabling project
teams to have their own installation guides. The content may start
out as lower quality than what the documentation team is currently
producing, but it will be *something*, and it can improve over time. I
think that's a reasonable trade-off.

> 
> Regarding use of installation content from the developer reference guides...
> 
> We can't maintain the proactive nature, consistent structure, and quality
> of the installation guide by referencing content in a bunch of disparate
> repositories. We also can't easily manage bugs in those repositories.

As I described above, I don't think we want you to. We want to make it
easier for more teams to write more guides, not ask you to do more work
yourself.

Placing the content in a separate manual will make it a bit less
discoverable, but we can solve that problem by providing links to
the documents along with the other guides. As long as it's clear
that the project team owns its guide, bugs and issues will feed
back to them instead of the doc team.

> 
> Regarding Debian, and I'll be brief...
> 
> The Debian instructions haven't worked nor received sufficient attention to
> resolve significant issues since I began using OpenStack. In fact, I chose
> Debian for my first installation and quickly changed to Ubuntu after
> getting stuck prior to the nova-neutron interaction problem. We try to
> reuse as much content as possible. For example, the configuration for each
> service shouldn't depend on distribution. Debian uses a unique GUI-style
> mechanism rather than editing files to configure OpenStack services. This
> mechanism not only prevents content reuse but also often lacks
> configuration changes and recommendations for each release. Furthermore, it
> forces us to rely on package maintainers to implement these changes and
> recommendations. We could easily disable this mechanism and more or less
> follow the instructions for Ubuntu with a different source of packages, but
> the primary maintainer of those packages won't let us do it. The Debian
> content consumes a considerable amount of space in the source and we can't
> reuse it, so we're removing it to ease content contributions for the
> distributions we publish.
> 
> Long story short...
> 
> We get plenty of empty commitments from developers and operators. If you
> want to change the installation guide, convert your energy from complaining
> about it to actually doing something about it.

Yep, the intent of my contributions to this thread are to push the
conversation in the direction of making that possible. Teams that
want to publish their own installation guide feel that publishing
it under /developer makes it hard to find and gives it the appearance
of a second-class citizen. They want to write their own content and
publish it alongside other related content, in the same way that
they publish their release notes, build artifacts, etc. We just
need to work out how to make that possible for documentation now.

Doug

> 
> Matt
> 
> On Wed, Mar 30, 2016 at 7:46 AM, Doug Hellmann <doug at doughellmann.com>
> wrote:
> 
> >
> >
> > On Wed, Mar 30, 2016, at 03:37 AM, Thomas Goirand wrote:
> > > On 03/29/2016 08:33 PM, Doug Hellmann wrote:
> > > > If the core doc team isn't able to help you maintain it, maybe it's a
> > > > candidate for a separate guide, just like we're discussing for projects
> > > > that aren't part of the DefCore set included in the main guide.
> > > >
> > > > Doug
> > >
> > > This is exactly what I don't want. Only installing the packages
> > > themselves is different. Like for example, "apt-get install foo" and
> > > answering a few debconf prompts is often enough to get packages to work,
> > > without the need for manual setup of dbs, or rabbitMQ credentials. But
> > > that's maybe 20% of the install-guide, and the rest of is left
> > > untouched, with no conditionals. For example the description of the
> > > services, testing them after install, etc. Having a separated guide
> > > would mean that someone would be left to write a full install-guide from
> > > scratch, alone. That isn't desirable.
> > >
> > > It is also my hope that the packaging on upstream infra will get going.
> > > If it does, it will make more sense to get the Debian guide up to speed,
> > > and probably there will be more contributors.
> >
> > Perhaps that common content should be a separate guide? I don't know the
> > best solution, but I don't think requiring any one team to keep up with
> > *everything* needed to install all projects on all platforms using all
> > available tools is the right approach. See Conway's Law.
> >
> > Doug
> >
> > >
> > > Cheers,
> > >
> > > Thomas Goirand (zigo)
> > >
> > >
> > >
> > __________________________________________________________________________
> > > OpenStack Development Mailing List (not for usage questions)
> > > Unsubscribe:
> > > OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> > __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >