Open Stack

On 13/09/13 05:41, Monty Taylor 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.

+1

>>> 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?
>>>
>>>
>> 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. :)

Yes and no. When new API versions arrive, they always arrive with a 
particular release. So we do need some way to ensure the docs go live at 
the right time, but I think Steve's suggestion for handling that is fine.

cheers,
Zane.