Open Stack

On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter <
mike.asthalter at rackspace.com> wrote:

>  Hi Anne,
>
>  I want to make sure I've understood the ramifications of your statement
> about content sharing.
>
>  So for now, until the infrastructure team provides us with a method to
> share content between repos, the only way to share the content from the
> orchestration wadl with the api-ref doc (
> https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml)
> is to manually copy the content from the orchestration wadl to the original
> heat wadl and then use that for the shared content. So we will not delete
> the original heat wadl until that new method of content sharing is in
> place. Is this correct?
>
>
Hi Mike,
It sounds like the dev team is fine with deleting that "original" heat WADL
and only maintaining one from here forward.

The way they will control Icehouse edits to the heat WADL that shouldn't
yet be displayed to end users is to use the "Work In Progress" button on
review.openstack.org. When a patch is marked WIP, you can't merge it.

So, you can safely delete the original Heat WADL and then from your dev
guides, if you want to include a WADL, you can point to the one in the
api-site repository. We now have a mirror of the github.com repository at
git.openstack.org that gives you access to the WADL in the api-site
repository at all times. I can walk you through building the URL that
points to the WADL file.

What we also need to build is logic in the build jobs so that any time the
api-site WADL is updated, your dev guide is also updated. This is done in
the Jenkins job in
https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml.
I can either submit this patch for you, or I'll ask Steve or Zane to do so.

Hope this helps -

Anne


>
>  Thanks!
>
>  Mike
>
>   From: Anne Gentle <annegentle at justwriteclick.com>
> Reply-To: OpenStack Development Mailing List <
> openstack-dev at lists.openstack.org>
> Date: Thursday, September 12, 2013 11:32 PM
> To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org>
> Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls
> moving forward
>
>
>
>
> On Thu, Sep 12, 2013 at 10:41 PM, Monty Taylor <mordred at inaugust.com>wrote:
>
>>
>>
>> On 09/12/2013 04:33 PM, Steve Baker wrote:
>> > On 09/13/2013 08:28 AM, Mike Asthalter wrote:
>> >> Hello,
>> >>
>> >> Can someone please explain the plans for our 2 wadls moving forward:
>> >>
>>  >>   * wadl in original heat
>> >>     repo:
>> https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl
>> >>     <%22
>> https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1
>> .>
>> >>   * wadl in api-site
>> >>     repo:
>> https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
>> >>
>> > The original intention was to delete the heat wadl when the api-site one
>> > became merged.
>>
>
>  Sounds good.
>
>
>> >> 1. Is there a need to maintain 2 wadls moving forward, with the wadl
>> >> in the original heat repo containing calls that may not be
>> >> implemented, and the wadl in the api-site repo containing implemented
>> >> calls only?
>> >>
>> >>     Anne Gentle advises as follows in regard to these 2 wadls:
>> >>
>> >>     "I'd like the WADL in api-site repo to be user-facing. The other
>> >>     WADL can be truth if it needs to be a specification that's not yet
>> >>     implemented. If the WADL in api-site repo is true and implemented,
>> >>     please just maintain one going forward."
>> >>
>> >>
>> >> 2. If we maintain 2 wadls, what are the consequences (gerrit reviews,
>> >> docs out of sync, etc.)?
>> >>
>> >> 3. If we maintain only the 1 orchestration wadl, how do we want to
>> >> pull in the wadl content to the api-ref doc
>> >> (
>> https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml
>>  >> <%22
>> https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docb
>> >)
>> >> from the orchestration wadl in the api-site repo: subtree merge, other?
>> >>
>> >>
>>
>
>  Thanks Mike for asking these questions.
>
>  I've been asking the infrastructure team for help with pulling content
> like the current nova request/response examples into the api-site repo. No
> subtree merges please. We'll find some way. Right now it's manual.
>
>
>> > These are good questions, and could apply equally to other out-of-tree
>> > docs as features get added during the development cycle.
>> >
>> > I still think that our wadl should live only in api-site.  If api-site
>> > has no branching policy to maintain separate Havana and Icehouse
>> > versions then maybe Icehouse changes should be posted as WIP reviews
>> > until they can be merged.
>>
>>  I believe there is no branching in api-site because it's describing API
>> and there is no such thing as a havana or icehouse version of an API -
>> there are the API versions and they are orthogonal to server release
>> versions. At least in theory. :)
>>
>
>  Yep, that's our working theory. :)
>
>  Anne
>
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
>  --
> Anne Gentle
> annegentle at justwriteclick.com
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130913/fbf9d172/attachment.html>