Open Stack

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<applewebdata://ADF909E2-ABA6-4E57-81C2-41FC459CA6DF/%22https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docb>) 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?


Thanks!

Mike

From: Anne Gentle <annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>>
Reply-To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto: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<mailto: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<mailto: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
>>     <%22https://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
>> <%22https://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<mailto:OpenStack-dev at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



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