Open Stack

On Sun, May 8, 2016 at 7:54 PM, Thomas Goirand <zigo at debian.org> wrote:

> On 05/08/2016 11:42 AM, Andreas Jaeger wrote:
> > On 05/07/2016 11:15 AM, Thomas Goirand wrote:
> >> Hi,
> >>
> >> During the Austin summit, I could discuss with Lana about what could be
> >> done for the Debian support in the install-guide.
> >>
> >> Currently, there's these facts:
> >> - The Debconf support adds lots of conditionals which aren't easy to
> >> support (ie: it makes the individual foo-install.rst more complicated).
> >> - Some people would prefer to document the non-interactive mode.
> >> - Some people (like me) would still prefer to keep supporting using
> >> Debconf during the installation.
> >>
> >> As a consequence, we believe the most easy way forward is as follow:
> >> - Keep Debian support directly in the install-guide.
> >> - Remove conditionals for Debian using Debconf in the foo-install.rst
> >> files, and document there the DEBIAN_FRONTEND=noninteractive mode.
> >
> > Exactly, that's what we all agreed on in the Install Guide session in
> > Austin.
> >
> >> - Push Debconf support in separate foo-debconf-install.rst files, and
> >> use them to generate the install-guide instead of the normal files.
> >
> > I don't understand what you want to do here - and especially how you do
> > this to make it in a way that is easy to support.
>
> Lets take an actual example. For setting-up glance, we have
> glance-install.rst. My proposal is to create a
> glance-debconf-install.rst which will be used only in the case of Debian
> when using Debconf. This file will be less than 30 lines in this case
> (as mostly, "apt-get install glance" is the only thing there is to
> document). It will be used instead of glance-install.rst, which would go
> out of that guide.
>
> > We discussed briefly in the meeting a Debconf guide and our consensus
> > was that any *automatic* setup would be done in a separate repository.
>
> There's nothing automatic in Debconf, everything is still prompted. So
> if this was the consensus, it's built around a wrong assumption.
>
> BTW, I'd be very careful with things discussed "briefly" and the feeling
> that there's a "consensus" in a room with only a small subset of
> everyone there. Our past discussions showed there was no such a general
> consensus.
>
> But anyway, I'm trying to make the effort to go on the direction of the
> doc's team, and finding an arrangement that will make everyone happy, so
> let's not discuss that, and hopefully, you will agree with my current plan.
>
> > Sourcing an additional debconf guide looks likes making everything much
> > more difficult...
>
> Right now, if I understand correctly, the problem is that we have rather
> big files, like glance-install.rst (ie: 330 lines), which the Debconf
> implementation replaces by only a few lines. So instead of having 300
> lines full of conditionals for this reason, we move it to the index,
> which will be the only place to change.
>
> Wont it be a lot easier this way? If not, then this plan is wrong, and
> should be rethought. But I really don't see how it will become harder.
> The index files are not touched often, they are very simple and short.
> Having a conditional there will be trivial to manage, and we wont have
> issues with alignment, which showed to be very painful in the
> *-install.rst individual files.
>
>
Conditionals in index.rst and toctrees are super buggy. See
http://lists.openstack.org/pipermail/openstack-docs/2015-February/005863.html
This
is a good example of why a spec helps us all get clarity and avoid pitfalls.


> > Let's do this in steps:
> >
> > * Get existing guide building for Debian again
> > * Rework existing guide so that it uses the non-interactive mode
> > * Write a spec explaining how your debconf guide should look like and
> > discuss that.
> > * Implement that spec
>
> Unfortunately, the schedule you're talking about above doesn't match the
> workflow that I am thinking of. I'd like to *move* some of the debconf
> content to some new foo-debconf-install.rst instead of foo-install.rst,
> keeping the screenshots, links and all. My intention was to work chapter
> by chapter, instead of a huge patch. It wouldn't be convenient to delete
> the content, write the spec, then re-add things back again.
>

I don't think "delete, spec, re-add" is what is proposed above. I think
it's "revise, test, re-add links," where revise means to match the rest of
the source files, without debconf.

One area to clarify -- I'm not sure if you're getting the existing guide
building for Debian on master for mitaka basically? I saw it as rework
existing guide (on master?) so that it doesn't use debconf, then test and
publish. Is that right? Then, would the revised guide be published from
stable/mitaka first?


>
> Also, I doubt that we need a spec for implementing this. We're also all
> short in time, I can already foresee the spec taking months to be
> approved, with comments on the English wording of the spec and so on...
> Please let's avoid this and simply discuss it in this list!
>

It has become clear on the list that we don't all understand the proposed
plan, heh. Pretty sure your current proposal needs some technical review if
you're thinking about using conditionals in toctree because it simply won't
work unless you're better at debugging than I am (would be nice if you
are). I empathize with the "fast, please" request, but at the same time, we
don't want to misstep (and trip) due to speed.

Anne


>
> So, comments welcome...
>
> Cheers,
>
> Thomas Goirand (zigo)
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160509/4299f02a/attachment.html>