Open Stack

On 14/04/16 04:32, Andreas Jaeger wrote:
> On 04/13/2016 08:01 PM, Amrith Kumar wrote:
>> Andreas,
>>
>> Thanks for your email. I am aware of the reviews you describe below but I was still under the impression that the status from the email on openstack-docs (Mitaka Install Guide testing) [1] and [2] were still valid.
>>
>> The understanding I had from those email threads is that the door hadn't yet closed. But I'll defer to the doc team; I think you understand the motivation for my request, and I respect (and fully admit that I don't understand) the complexities involved in releasing documentation.

Sorry for the confusion on this one, it's my fault as I've been giving some mixed messages.

We didn't approve the spec late in March[1], simply because it was too late to propose large scale changes while we were in the throes of testing the Install Guide.

What then happened was that the changes were proposed anyway[2], and we (predictably, given that we hadn't approved the spec) blocked them. However, Matt (who was doing the bulk of the testing) mentioned on the mailing list that they could potentially be merged, as they were "a relatively simple/optional service and the patch in the review queue looks fairly complete"[3]. So I definitely dropped a ball in not going back and working out whether or not to merge it. However, even if it had been merged, it still would have remained untested, which was the reason we declined the spec and the patch in the first place.

Because we don't branch the Install Guide until some weeks after the release date (this is so that we can complete testing against final packages, rather than rely on pre-release packages), I think it's feasible to have this go in to the Kilo release at this stage. However, it will be untested against Kilo (and will require a note stating that) and, as Andreas noted, with large scale changes to the Install Guide looming for Newton, could be completely redesigned or removed in the next release.

If you're happy with that solution, and Andreas and Matt agree, I support having that patch merge any time (Andreas' option #2).

Again, I apologise, as I did drop the ball on this and forgot to go back and check the patch before release, but thanks for bringing it up, and hopefully this will help us sort it out.

L

1: https://review.openstack.org/#/c/290053
2: https://review.openstack.org/#/c/298929/
3: http://lists.openstack.org/pipermail/openstack-docs/2016-March/008385.html

> 
> Indeed, that was stated as an option there - and it seems we didn't
> followup on this one in either direction. Sorry about that,
> 
>> I trust that if it is at all possible, you will accommodate the request. Of your options below, I would request #2 if at all possible.
> 
> If Matt and Lana are still fine, #2 would work for me,
> 
> Andreas
> 
>> Thanks,
>>
>> -amrith
>>
>>
>> [1] http://lists.openstack.org/pipermail/openstack-docs/2016-March/008385.html
>> [2] http://lists.openstack.org/pipermail/openstack-docs/2016-March/008387.html
>>
>>
>>
>>> -----Original Message-----
>>> From: Andreas Jaeger [mailto:aj at suse.com]
>>> Sent: Wednesday, April 13, 2016 1:46 PM
>>> To: Amrith Kumar <amrith at tesora.com>; OpenStack Development Mailing List
>>> (not for usage questions) <openstack-dev at lists.openstack.org>
>>> Cc: mkassawara at gmail.com; Lana Brindley <openstack at lanabrindley.com>; Mike
>>> Perez <mike at openstack.org>; openstack-docs at lists.openstack.org
>>> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore
>>> - What about big tent?
>>>
>>> On 04/13/2016 07:17 PM, Amrith Kumar wrote:
>>>> Andreas, Lana, Mike, Matt, and others who've been active on this
>>>> thread,
>>>>
>>>> I've been following this conversation about installation documentation
>>> and core vs. non-core projects from afar and was under the impression that
>>> the changes being proposed would take effect for Newton and moving
>>> forward.
>>>>
>>>> Today I was informed that after a lot of effort and testing, the
>>> installation guide for Trove/Mitaka which is ready and up for review[1]
>>> has been placed on hold pending the outcome of your discussions in Austin.
>>>
>>>> The documentation that is now available and ready for review is for the
>>> Mitaka series and should not, I believe, be held up because there is now a
>>> proposal afoot to put non-core project installation guides somewhere else.
>>> If we choose to do that, that's a conversation for Newton, I believe, and
>>> I believe that the Trove installation guide for Mitaka should be
>>> considered for inclusion along with the other Mitaka documentation.
>>>
>>> Amrith, I'm a bit surprised by this email and request. So, let me give
>>> some more context.
>>>
>>> There's a spec out:
>>> https://review.openstack.org/#/c/290053 for this work which came very
>>> late. Bogdan asked on the 23rd of March, and I commented on the spec with
>>> -1 on the 27th of March that this is a post-Mitaka topic. Then, on the
>>> 29th of March, your referenced change gets submitted -without any followup
>>> discussion on the spec.
>>>
>>> Would you have taken a code change under these conditions for trove
>>> itself?
>>>
>>> While I applaud your team's work, the documentation team also needs to
>>> review content you propose for consistency - and that takes time. We're
>>> still flashing out some details for some of the guides for Mitaka.
>>>
>>>> The lack of installation guides for a project is a serious challenge for
>>> deployers and users, and much work has been expended getting the Trove
>>> documentation ready and thoroughly tested on Ubuntu, RDO and SUSE.
>>>>
>>>> I'm therefore requesting that the doc team consider this set of
>>> documentation for the Mitaka series and make it available with the other
>>> install guides for other projects after it has been reviewed, and not hold
>>> it subject to the outcome of some Newton focused discussion that is to
>>> happen in Austin.
>>>
>>> I'm glad about the work the team has done and will not block this going in
>>> on my own. IMHO think we have the following options:
>>>
>>> 1) Wait until Austin and speed track this change afterwards based on the
>>> outcome of the discussion there if possible.
>>> 2) Take the change in with the explicit understanding that it might be
>>> taken out again based on the general Install Guide discussion.
>>> 3) Do nothing for Mitaka.
>>>
>>> I'm happy to take my -2 away from the change after the spec has been
>>> approved and we've decided which of the options  to take - and for that I
>>> defer to Lana and Matt.
>>>
>>> So, let's discuss how to move forward on the documentation list with the
>>> docs team and see what they suggest,
>>>
>>> Andreas
>>>
>>>> Thanks,
>>>>
>>>> -amrith
>>>>
>>>>
>>>> [1] https://review.openstack.org/#/c/298929/
>>>>
>>>>> -----Original Message-----
>>>>> From: Andreas Jaeger [mailto:aj at suse.com]
>>>>> Sent: Monday, April 04, 2016 2:42 PM
>>>>> To: OpenStack Development Mailing List (not for usage questions)
>>>>> <openstack-dev at lists.openstack.org>
>>>>> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover
>>>>> Defcore
>>>>> - What about big tent?
>>>>>
>>>>> On 04/04/2016 12:12 PM, Thierry Carrez wrote:
>>>>>> Doug Hellmann wrote:
>>>>>>>> [...]
>>>>>>>> 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.
>>>>>>
>>>>>> Yes, the base install guide should ideally serve as a reference to
>>>>>> reach that first step where you have all the underlying services
>>>>>> (MySQL,
>>>>>> Rabbit) and a base set of functionality (starterkit:compute ?)
>>>>>> installed and working. That is where we need high-quality,
>>>>>> proactively-checked, easy to understand content.
>>>>>>
>>>>>> Then additional guides (ideally produced by each project team with
>>>>>> tooling and mentoring from the docs team) can pick up from that base
>>>>>> first step, assuming their users have completed that first step
>>>>>> successfully.
>>>>>>
>>>>>
>>>>> Fully agreed.
>>>>>
>>>>> I just wrote a first draft spec for all of this and look forward to
>>>>> reviews.
>>>>>
>>>>> I'll enhance some more tomorrow, might copy a bit from above (saw
>>>>> this too late).
>>>>>
>>>>> https://review.openstack.org/301284
>>>>>
>>>>> Andreas
>>>>> --
>>>>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>>>>>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>>>>    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>>>>>        HRB 21284 (AG Nürnberg)
>>>>>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272
>>>>> A126
>>>>>
>>>>>
>>>>> _____________________________________________________________________
>>>>> _____ 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
>>>>
>>>
>>>
>>> --
>>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>>>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>>    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>>>        HRB 21284 (AG Nürnberg)
>>>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>>
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
> 
> 

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160414/1799bd54/attachment.pgp>