<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Sep 2, 2014 at 7:05 PM, Waines, Greg <span dir="ltr"><<a href="mailto:Greg.Waines@windriver.com" target="_blank">Greg.Waines@windriver.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 lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">A question about the 2013.2 tag on the openstack doc APIs …<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">Background:<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">my company, WindRiver, provides an enhanced OpenStack distribution<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">which has resulted in us extending/enhancing the OpenStack REST APIs<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">In order to provide updated OpenStack REST APIs, we are:<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">including the api-site, compute-api, image-api, etc. gits
<br>
as sub-gits in our git repository<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">and<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">the plan is for us to increment our changes on top of these opensource gits<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">Question:<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">the latest git ‘tag’ for these api doc gits seems to be ‘2013.2’<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span></span></span></p></div></div></blockquote><div>We originally tagged this repo just for tracking stats if my memory serves. There's no meaning to a "release" of API docs, because we (upstream docs for OpenStack) cannot predict how a cloud provider will implement their API endpoints and which API versions they will implement. </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 lang="EN-US" link="blue" vlink="purple">
<div>
<p><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">so we have included the sub-gits at this tag<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">however<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">when I try to generate sources<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">i.e. mvn clean generate-sources<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">in (say) the compute-api git, I have the following problems:<u></u><u></u></span></p>
<p style="margin-left:1.5in">
<u></u><span style="font-size:11pt;font-family:Wingdings;color:rgb(31,73,125)"><span>§<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">in ./compute-api/openstack-compute-api-2/src/<u></u><u></u></span></p>
<p style="margin-left:2in">
<u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">in file: os-compute-devguide.xml:<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2.5in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">…<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <wadl:resources<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> xmlns:wadl="<a href="http://wadl.dev.java.net/2009/02" target="_blank">http://wadl.dev.java.net/2009/02</a>"><u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <wadl:resource<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> href="<a href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/wadl/os-compute-2.wadl#ips" target="_blank">http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/wadl/os-compute-2.wadl#ips</a>"/><u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <wadl:resource<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> href="<a href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/wadl/os-compute-2.wadl#network_label" target="_blank">http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/wadl/os-compute-2.wadl#network_label</a>"<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> /><u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> </wadl:resources><u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:2.5in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">…<u></u><u></u></span></p>
<p style="margin-left:2in">
<u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">??? this ‘plain’ directory does not exist in the ‘api-site’ git ???<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">… so the make of the PDF fails.<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span></span></span></p></div></div></blockquote><div><br></div><div>Right, it's "raw" in github and "plain" in our mirror. </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 lang="EN-US" link="blue" vlink="purple">
<div>
<p style="margin-left:1in"><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">… and for me (and maybe others doing the same doc extensions as me),
<br>
it is not good to be referencing the .wadl files from the api-site git @ //<a href="http://git.openstack.org" target="_blank">git.openstack.org</a> …<br>
instead of a local version of this api-site git.<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">I do notice that in the current/master version of the api-site and compute-api gits,<br>
almost everything seems to be moved to the api-site git … i.e. there is an api-ref-guides/ directory now in api-site<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">??? maybe this was to deal with the cross-git reference issues ???<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> </span></p></div></div></blockquote><div><br></div><div>There are two reasons going on here: </div><div>1. We, upstream OpenStack, can't rely on github to be there with the uptime we need, so we mirror it with our own infra resources.</div>
<div>2. Yes, we had problems building when we had to rely on a change in two separate repos to land with similar timing.</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 lang="EN-US" link="blue" vlink="purple"><div><p style="margin-left:1in"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Symbol;color:rgb(31,73,125)"><span>·<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">finally, … how come there are no more recent tags than ‘2013.2’ ?<u></u><u></u></span></p>
<p style="margin-left:1in">
<u></u><span style="font-size:11pt;font-family:'Courier New';color:rgb(31,73,125)"><span>o<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">
</span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">ideally would be nice if there was a tag that represented the version of openstack that the documentation was consistent with e.g. ‘havana’ or ‘icehouse’
… <u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u></span></p></div></div></blockquote><div><br></div><div>We have had this discussion in the past, read it at <a href="http://lists.openstack.org/pipermail/openstack-docs/2014-April/004337.html">http://lists.openstack.org/pipermail/openstack-docs/2014-April/004337.html</a>. The basic problem with tagging API docs is that there's not a map from say, havana, to API versions. The deployers choices for that particular release would look something like this:</div>
<div><br></div><div>Block Storage API v1 or v2</div><div>Compute API v2</div><div>Identity API v2.0 or v3</div><div>Image Service v1, v1.1, or v2</div><div>(not Database service, they weren't integrated then)</div><div>
Networking API v2.0</div><div>Object Storage v1</div><div>Orchestration v1</div><div>Telemetry v2</div><div><br></div><div>So I think there are 3*2*3*4*2*2*2*2 = 1152 possibilities of combining API versions a cloud provider offers for Havana, where you can choose not to deploy an API endpoint at all. We can't dictate to the provider "you must run these API versions when running havana" so I've avoided tagging the docs for overhead and maintenance and explanatory reasons. :) </div>
<div><br></div><div>Hopefully these explanations makes sense to you, sounds like you've guessed right all along. I certainly want our docs to be re-used and they're licensed completely for re-use, but I'm pretty sure I can't accurately say which API calls go with a particular release. I definitely want to hear ideas though!</div>
<div>Thanks for asking -</div><div>Anne</div><div><br></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 lang="EN-US" link="blue" vlink="purple"><div><p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">thanks in advance,<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">Greg.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif"><u></u> <u></u></span></p>
</div>
</div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br></div></div>