Open Stack

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130912/7d7cbcee/attachment.html>