Open Stack

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.

> 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.

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!

So, comments welcome...

Cheers,

Thomas Goirand (zigo)