<div dir="ltr">Hi,<div><br></div><div>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.</div><div><br></div><div>First, a little history about the guide...</div><div><br></div><div>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 <a href="http://ask.openstack.org">ask.openstack.org</a>, 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.</div><div><br></div><div>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.</div><div><br></div><div>Regarding use of distribution packages instead of source...</div><div><br></div><div>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.<br></div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Regarding use of installation content from the developer reference guides...</div><div><br></div><div>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.</div><div><br></div><div>Regarding Debian, and I'll be brief...</div><div><br></div><div>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.</div><div><br></div><div>Long story short...</div><div><br></div><div>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.</div><div><br></div><div>Matt</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Mar 30, 2016 at 7:46 AM, Doug Hellmann <span dir="ltr"><<a href="mailto:doug@doughellmann.com" target="_blank">doug@doughellmann.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
<br>
On Wed, Mar 30, 2016, at 03:37 AM, Thomas Goirand wrote:<br>
> On 03/29/2016 08:33 PM, Doug Hellmann wrote:<br>
> > If the core doc team isn't able to help you maintain it, maybe it's a<br>
> > candidate for a separate guide, just like we're discussing for projects<br>
> > that aren't part of the DefCore set included in the main guide.<br>
> ><br>
> > Doug<br>
><br>
> This is exactly what I don't want. Only installing the packages<br>
> themselves is different. Like for example, "apt-get install foo" and<br>
> answering a few debconf prompts is often enough to get packages to work,<br>
> without the need for manual setup of dbs, or rabbitMQ credentials. But<br>
> that's maybe 20% of the install-guide, and the rest of is left<br>
> untouched, with no conditionals. For example the description of the<br>
> services, testing them after install, etc. Having a separated guide<br>
> would mean that someone would be left to write a full install-guide from<br>
> scratch, alone. That isn't desirable.<br>
><br>
> It is also my hope that the packaging on upstream infra will get going.<br>
> If it does, it will make more sense to get the Debian guide up to speed,<br>
> and probably there will be more contributors.<br>
<br>
</span>Perhaps that common content should be a separate guide? I don't know the<br>
best solution, but I don't think requiring any one team to keep up with<br>
*everything* needed to install all projects on all platforms using all<br>
available tools is the right approach. See Conway's Law.<br>
<span class="HOEnZb"><font color="#888888"><br>
Doug<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
><br>
> Cheers,<br>
><br>
> Thomas Goirand (zigo)<br>
><br>
><br>
> __________________________________________________________________________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe:<br>
> <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div>