Open Stack

On Tue, Sep 2, 2014 at 7:05 PM, Waines, Greg <Greg.Waines at windriver.com>
wrote:

>  A question about the 2013.2 tag on the openstack doc APIs …
>
>
>
> Background:
>
> ·         my company, WindRiver, provides an enhanced OpenStack
> distribution
>
> ·         which has resulted in us extending/enhancing the OpenStack REST
> APIs
>
> ·
>
> ·         In order to provide updated OpenStack REST APIs, we are:
>
> o   including the api-site, compute-api, image-api, etc.  gits
> as sub-gits in our git repository
>
> o   and
>
> o   the plan is for us to increment our changes on top of these
> opensource gits
>
>
>
> Question:
>
> ·         the latest git ‘tag’ for these api doc gits seems to be ‘2013.2’
>
> 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.


> ·         so we have included the sub-gits at this tag
>
> ·
>
> ·         however
>
> o   when I try to generate sources
>
> o   i.e.    mvn clean generate-sources
>
> o   in (say) the compute-api git, I have the following problems:
>
> §  in ./compute-api/openstack-compute-api-2/src/
>
> ·         in file:  os-compute-devguide.xml:
>
> …
>
>             <wadl:resources
>
>                 xmlns:wadl="http://wadl.dev.java.net/2009/02">
>
>                 <wadl:resource
>
>                     href="
> http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/wadl/os-compute-2.wadl#ips
> "/>
>
>                 <wadl:resource
>
>                     href="
> http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/wadl/os-compute-2.wadl#network_label
> "
>
>                 />
>
>             </wadl:resources>
>
> …
>
> ·         ??? this ‘plain’ directory does not exist in the ‘api-site’ git
> ???
>
> o   … so the make of the PDF fails.
>
>
Right, it's "raw" in github and "plain" in our mirror.


> o
>
> o   … and for me (and maybe others doing the same doc extensions as me),
> it is not good to be referencing the .wadl files from the api-site git @ //
> git.openstack.org …
> instead of a local version of this api-site git.
>
> o
>
> ·
>
> ·         I do notice that in the current/master version of the api-site
> and compute-api gits,
> almost everything seems to be moved to the api-site git … i.e. there is an
> api-ref-guides/ directory now in api-site
>
> o   ??? maybe this was to deal with the cross-git reference issues ???
>
> o
>

There are two reasons going on here:
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.
2. Yes, we had problems building when we had to rely on a change in two
separate repos to land with similar timing.


>  ·
>
> ·         finally, … how come there are no more recent tags than ‘2013.2’
> ?
>
> o   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’ …
>
>
We have had this discussion in the past, read it at
http://lists.openstack.org/pipermail/openstack-docs/2014-April/004337.html.
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:

Block Storage API v1 or v2
Compute API v2
Identity API v2.0 or v3
Image Service v1, v1.1, or v2
(not Database service, they weren't integrated then)
Networking API v2.0
Object Storage v1
Orchestration v1
Telemetry v2

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

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!
Thanks for asking -
Anne



>
>
>
>
> thanks in advance,
>
> Greg.
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140902/d6781f84/attachment-0001.html>