Open Stack

Hi Infra team,

sorry, I missed Clark's followup since I wasn't subscribed to the infra
mailing list - but now I am.

On Mon, Dec 9, 2013 Clark Boylan wrote:
> On Mon, Dec 9, 2013 at 11:51 AM, Andreas Jaeger <aj at suse.com> wrote:
>> The OpenStack docu team now has a repository called
>> openstack-doc-tools for their automation tools and gate tests.
>>
>> I'd like to get some advise on how to use the tool for working with
>> the various repositories we have.
>>
>> Does the infra team has any recommendation on how to move forward?
>>
>> For building documentation with Jenkins, I see two options:
>>
>> Option 1: Have Jenkins checkout the openstack-doc-tools repository
>>           every time and use that for building - similar to the
>>           "devstack-checkout" job.
>>
>>           This would mean that directly after every change done in
>>           openstack-doc-tools, the tools are used for checking of all
>>           gated repositories.
>>
>> Option 2: Copy the tools and all support files to each and every
>>           repository. We could automate that.
>>
>> Moving forward, I'd like to have all our repositories (api-site,
>> compute-api, identity-api, image-api, netconn-api, object-api,
>> volume-api, operations-guide, openstack-manuals) use proper gates,
>> thus extend "test.py" so that it can be used in more places. Note that
>> the $service-api repos will be moved to $project/doc/source - we then
>> should gate on those.
>>
>> Right now only operations-guide and openstack-manuals are gated - but
>> operations-guide uses an old version of the tools.
>>
>> So, I want to move forward with these steps:
>> 1) Properly setup openstack-doc-tools project, there are some open
>>    reviews that need to go in.
>> 2) Use openstack-doc-tools in openstack-manuals and operations-guide
>> 3) Use openstack-doc-tools for gating of api-site
>> 4) Use openstack-doc-tools for gating of $service api repos
>>[[...]
>
> I have removed the cross post to openstack-docs as I think this is an
> infra discussion.
>
> Option 2 is something that should be avoided. The file copying with
> oslo is problematic for many reasons and I don't think we get any of
> the benefits from that process with the doc tools (we don't have to
> worry about internal code APIs). Option 1 is a possibility.
>
> There are also at least two more options that I think we should consider:
> Option 3: Make doc-tools an installable package that the jenkins jobs
> can install as a dependency (similar to any of the python dependencies
> in the various projects).
> Option 4: Install doc-tools globally on the test slaves with puppet
> and manage the install with puppet. Then the doc jobs can just assume
> the doc-tools are present and use them.
>
> I am a fan of option 3 myself. It fits into the way we deal with most
> other job dependencies and makes it easy for folks at home to do that
> same.
>
> Once this is sorted out the four steps above should be able to move
> forward without infra interaction. The docs jobs would simply be
> updated as appropriate.

Thanks Clark for the suggestions, Option 3 sounds to me the best way
forward.

I've made an initial python package now out of openstack-doc-tools.

I've briefly discussed with Fungi on IRC on the next steps.
He mentioned that we need to get openstack-doc-tools uploading to pypi -
and a way to release a new package version with signed tags. Fungi, will
you do the pypi setup and explain what needs to be done with the signed
tags by the documentation team, please?

What do I then need to change in openstack-manuals to have it
automatically use the latest version of the package?

thanks for your help,
Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126