Open Stack

Hi Anne & Steve,

I already have removing the "original" heal WADL in my work plan.

I am just waiting for the released version of the clouddocs maven plugin to be fixed (1.10.0) to support pulling the wadl content into the  api-ref doc (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml) from the orchestration wadl in the api-ref site.

Mike

From: Steven Dake <sdake at redhat.com<mailto:sdake at redhat.com>>
Reply-To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Friday, September 20, 2013 2:46 PM
To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Cc: Anne Gentle <annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>>
Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward

On 09/13/2013 01:21 PM, Anne Gentle wrote:



On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter <mike.asthalter at rackspace.com<mailto: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<http://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<http://github.com> repository at git.openstack.org<http://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.


Anne,

Sorry for delay in response - I've been traveling.  I will submit a change to remove the wadl from the heat repo since  the api-site is finished.

Regards
-steve

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<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>

_______________________________________________
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>



_______________________________________________
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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130923/1009c7eb/attachment.html>