<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div>We were successful yesterday in accessing the orchestration-api wadl in the api-site repo from the api-ref dev guide (<span style="font-family: Cambria; font-size: 12px; color: rgb(27, 57, 245); "><span style="text-decoration: underline; "><a>https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml</a></span></span><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; ">)
in the original heat repo using the following syntax in the api-ref.xml doc:</span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; "><br>
</span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; ">
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #b14314">
<span style="color: #0d21a0"><wadl:resources</span><span style="color: #000000"><br>
</span><span style="color: #ff9667"> href</span><span style="color: #ff925c">=</span>"http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl"<span style="color: #000000"><br>
</span><span style="color: #ff9667"> </span><span style="color: #00abd2">xmlns:wadl</span><span style="color: #ff925c">=</span>"http://wadl.dev.java.net/2009/02"<span style="color: #0d21a0">/></span></p>
</span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; "><br>
</span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; ">Therefore, as recommended in our discussion on this mailing list last week, I am planning to submit a patch to delete the
original heat wadl (heat-api-1.0.wadl) and to point the api-ref.xml doc at the orchestration-api.wadl in the api-site repo, as shown above. </span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; "><br>
</span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; "><span class="Apple-style-span" style="background-color: rgb(255, 255, 0);">Please let me know by tomorrow if anyone has any
objections to deleting the original heat wadl, heat-api-1.0.wadl.</span></span></div>
<div><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; "><span class="Apple-style-span" style="background-color: rgb(255, 255, 0);"><br>
</span></span></div>
<div>On a related note, Anne Gentle has recommended the following:</div>
<div><br>
</div>
<div>"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 <a href="https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml">https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml</a>.
I can either submit this patch for you, or I'll ask Steve or Zane to do so."</div>
<div><br>
</div>
<div>Steve or Zane, is submitting this patch for the build logic something you would like to do, or should we ask Anne to take care of it?</div>
<div><br>
</div>
<div>Mike</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Calibri; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style="font-weight:bold">From: </span>Mike A <<a href="mailto:mike.asthalter@rackspace.com">mike.asthalter@rackspace.com</a>><br>
<span style="font-weight:bold">Reply-To: </span>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
<span style="font-weight:bold">Date: </span>Friday, September 13, 2013 3:39 PM<br>
<span style="font-weight:bold">To: </span>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward<br>
</div>
<div><br>
</div>
<div>
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div>Thanks for the clarification Anne!</div>
<div><br>
</div>
<div>I will see you about building the URL for access to the wadl in the api-site repo from the dev guide next week.</div>
<div><br>
</div>
<div>I think it's best to request Steve to submit the patch for logic in the build jobs to update the dev guide whenever the api-site wadl is updated, so he will be aware about it.</div>
<div><br>
</div>
<div>Mike</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Calibri; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style="font-weight:bold">From: </span>Anne Gentle <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br>
<span style="font-weight:bold">Reply-To: </span>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
<span style="font-weight:bold">Date: </span>Friday, September 13, 2013 3:21 PM<br>
<span style="font-weight:bold">To: </span>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward<br>
</div>
<div><br>
</div>
<div>
<div>
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter <span dir="ltr">
<<a href="mailto:mike.asthalter@rackspace.com" target="_blank">mike.asthalter@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="font-size:14px;font-family:Calibri,sans-serif;word-wrap:break-word">
<div>Hi Anne,</div>
<div><br>
</div>
<div>I want to make sure I've understood the ramifications of your statement about content sharing.</div>
<div><br>
</div>
<div>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 (<span style="font-family:Cambria;font-size:12px;color:rgb(27,57,245)"><span style="text-decoration:underline"><a>https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml</a></span></span><span style="font-style: normal; font-size: 14px; text-decoration: none; font-weight: normal; font-family: Calibri, sans-serif; ">)
is to manually copy the content from the orchestration wadl to the original heat wadl and then use that for the shared content. </span>So we will not delete the original heat wadl until that new method of content sharing is in place. Is this correct? </div>
<div><br>
</div>
</div>
</blockquote>
<div><br>
</div>
<div>Hi Mike,</div>
<div>It sounds like the dev team is fine with deleting that "original" heat WADL and only maintaining one from here forward.</div>
<div><br>
</div>
<div>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
<a href="http://review.openstack.org" target="_blank">review.openstack.org</a>. When a patch is marked WIP, you can't merge it. <br>
</div>
<div><br>
</div>
<div>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
<a href="http://github.com">github.com</a> repository at <a href="http://git.openstack.org">
git.openstack.org</a> 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.</div>
<div><br>
</div>
<div>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 <a href="https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml">https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml</a>.
I can either submit this patch for you, or I'll ask Steve or Zane to do so.</div>
<div><br>
</div>
<div>Hope this helps - </div>
<div><br>
</div>
<div>Anne</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="font-size:14px;font-family:Calibri,sans-serif;word-wrap:break-word">
<div></div>
<div><br>
</div>
<div>Thanks!</div>
<div><br>
</div>
<div>Mike</div>
<div><br>
</div>
<span>
<div style="border-width:1pt medium medium;border-style:solid none none;padding:3pt 0in 0in;text-align:left;font-size:11pt;font-family:Calibri;border-top-color:rgb(181,196,223)">
<span style="font-weight:bold">From: </span>Anne Gentle <<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>><br>
<span style="font-weight:bold">Reply-To: </span>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org" target="_blank">openstack-dev@lists.openstack.org</a>><br>
<span style="font-weight:bold">Date: </span>Thursday, September 12, 2013 11:32 PM<br>
<span style="font-weight:bold">To: </span>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org" target="_blank">openstack-dev@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward<br>
</div>
<div>
<div>
<div><br>
</div>
<div>
<div>
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Thu, Sep 12, 2013 at 10:41 PM, Monty Taylor <span dir="ltr">
<<a href="mailto:mordred@inaugust.com" target="_blank">mordred@inaugust.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div><br>
<br>
On 09/12/2013 04:33 PM, Steve Baker wrote:<br>
> On 09/13/2013 08:28 AM, Mike Asthalter wrote:<br>
>> Hello,<br>
>><br>
>> Can someone please explain the plans for our 2 wadls moving forward:<br>
>><br>
</div>
>> * wadl in original heat<br>
>> repo: <a href="https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl" target="_blank">
https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl</a><br>
>> <%22<a href="https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1" target="_blank">https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1</a>.><br>
>> * wadl in api-site<br>
<div>>> repo: <a href="https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl" target="_blank">
https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl</a><br>
>><br>
> The original intention was to delete the heat wadl when the api-site one<br>
> became merged.<br>
</div>
</blockquote>
<div><br>
</div>
<div>Sounds good. </div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div>>> 1. Is there a need to maintain 2 wadls moving forward, with the wadl<br>
>> in the original heat repo containing calls that may not be<br>
>> implemented, and the wadl in the api-site repo containing implemented<br>
>> calls only?<br>
>><br>
>> Anne Gentle advises as follows in regard to these 2 wadls:<br>
>><br>
>> "I'd like the WADL in api-site repo to be user-facing. The other<br>
>> WADL can be truth if it needs to be a specification that's not yet<br>
>> implemented. If the WADL in api-site repo is true and implemented,<br>
>> please just maintain one going forward."<br>
>><br>
>><br>
>> 2. If we maintain 2 wadls, what are the consequences (gerrit reviews,<br>
>> docs out of sync, etc.)?<br>
>><br>
>> 3. If we maintain only the 1 orchestration wadl, how do we want to<br>
>> pull in the wadl content to the api-ref doc<br>
>> (<a href="https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml" target="_blank">https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml</a><br>
</div>
>> <%22<a href="https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docb" target="_blank">https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docb</a>>)<br>
<div>>> from the orchestration wadl in the api-site repo: subtree merge, other?<br>
>><br>
>><br>
</div>
</blockquote>
<div><br>
</div>
<div>Thanks Mike for asking these questions. </div>
<div><br>
</div>
<div>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.</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</span>
<div>
<div><span>
<div>
<div>
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div>> These are good questions, and could apply equally to other out-of-tree<br>
> docs as features get added during the development cycle.<br>
><br>
> I still think that our wadl should live only in api-site. If api-site<br>
> has no branching policy to maintain separate Havana and Icehouse<br>
> versions then maybe Icehouse changes should be posted as WIP reviews<br>
> until they can be merged.<br>
<br>
</div>
I believe there is no branching in api-site because it's describing API<br>
and there is no such thing as a havana or icehouse version of an API -<br>
there are the API versions and they are orthogonal to server release<br>
versions. At least in theory. :)<br>
</blockquote>
<div><br>
</div>
<div>Yep, that's our working theory. :)</div>
<div><br>
</div>
<div>Anne </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
-- <br>
Anne Gentle<br>
<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div>
</div>
</div>
</span></div>
</div>
</div>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
</blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
-- <br>
Anne Gentle<br>
<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div>
</div>
</div>
</span></div>
</div>
</span>
</body>
</html>