Open Stack

I've been saying this for a while, but I think OpenGL does a very good job from a documentation perspective.

They document the core: http://www.opengl.org/registry/#apispecs
and then provide a list of possible extensions, in an extension registry:  http://www.opengl.org/registry/#arbextspecs

Keeping them separate makes it clear to devs  that the extensions are well extensions....not something you can count on..something you have to detect.

That said, product guys seem to freak out whenever we suggest that these should be documented separately because they see Core+Extensions as their product.

Anyway, I think we just need to educate our customers on what extensions are and how they work.

-jOrGe W.


On Dec 18, 2012, at 5:00 PM, Matt Dietz wrote:

That's quite the skew. :-\

I still hesitate regarding extensions because they seem to encourage people to write code that assumes said extensions will be present. Plus, as much as you want to call an API the core API, if someone shows a customer Core API++, they won't know the difference, and there's no trivial way to communicate that AFAICT. But I digress.

It really does sound like the best we could do is ask the endpoint for what's available (periodically, anyway) and display only those docs, but given that all extensions are enabled by default, I doubt it would really solve much. Seems that's the catch when everything is pluggable. I'd love to hear if anyone has really solved this well, though. I personally have no context for this particular problem

From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Reply-To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Tuesday, December 18, 2012 4:42 PM
To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: Re: [openstack-dev] Novaclient and Extensions


On Tue, Dec 18, 2012 at 1:26 PM, Matt Dietz <matt.dietz at rackspace.com<mailto:matt.dietz at rackspace.com>> wrote:
I agree with this

The only thing I would add is it would be ideal if the extensions were treated explicitly as extensions. More specifically, if the client documentation made it clear that extension X might not be available across all openstack clouds. That the client currently sorts the extensions docstrings in with the rest of the core functionality could lead to some confusion down the road.


Thinking about this, and what it really might look like to a user. I want to apply some hard data around this issue.

There are 32 viable core "calls" for the Compute API. [1] There are over 90 viable extension calls.[2] I haven't done the complete audit yet for missing docs for extensions, but I know that there's about a 3 times factor of core calls to extension calls based on the doc work I've done and managed.

Basically I need to point out that "make it clear in the docs" is not the best fix, and chasing true clarity is probably impossible knowing what's under the covers.

What can we do beyond docs?

Thanks,
Anne

1. I'm calling a "call" a GET, PUT, POST, DELETE request with an associated URI. Basically I'm counting the number of <method name="GET|PUT|POST|DELETE"> elements in WADL files.
2. There are 97 extension methods documented if you don't count volume creation or attachment, 113 total if you do volumes through the Compute API extension, see  https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdExERVZ0elAtc1pWcGtfQWNlMEFNd1E for counts.

From: Craig Vyvial <cp16net at gmail.com<mailto:cp16net at gmail.com>>

Reply-To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Tuesday, December 18, 2012 1:14 PM

To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: Re: [openstack-dev] Novaclient and Extensions

Ok i agree that the user should only have to know 1 thing. The entry point.

Then the discovery of extensions by the client should be api driven by the cloud entry point.


On Tue, Dec 18, 2012 at 6:03 AM, Christopher Yeoh <cyeoh at au1.ibm.com<mailto:cyeoh at au1.ibm.com>> wrote:
On Mon, 17 Dec 2012 22:37:50 -0800
Monty Taylor <mordred at inaugust.com<mailto:mordred at inaugust.com>> wrote:

> On 12/17/2012 10:20 PM, Craig Vyvial wrote:
> > I do not think making the client "smart" enough to be able to tell
> > which extensions are available is the right approach. It seems like
> > overkill for the client's responsibility.
> >
> > I maybe reading in to this to far but it seems like if you want to
> > install or enable an extension you should have to install to enable
> > it... aka install python-novaclient-security-groups.
> > Then each extension can be updated maintained separately.
> >
> > But i guess the main draw back I see with this is that then its a
> > pain to "test" this functionality between extensions and core code.
> > But I am sure people/companies have their own custom extensions that
> > have never made it into the core code or never will have already
> > felt some of these pains.
>
> Obviously, I agree with Vish here ... but I think that one of the
> places where you and I may be missing each other is in who the
> audience is we are talking about.
>
> When you say "if you want to install..." that implies a level of
> agency or understanding that I do not think we should expect from a
> public cloud user. Why would I, as a consumer of an OpenStack based
> public cloud ever "want" to install a novaclient extension module?
> How would I even know I want to do that?

+1

Most users would not know that they have to install an extension
and just finding out which extensions they should install would be
difficult for new and inexperienced users. They'd probably just assume
that the functionality they want is not available.

So I agree we want the client to automatically detect what
extension capabilities can be used. Perhaps even an easy way for them
to see what functionality they could have from nova client if the
corresponding server side support was installed.

Chris
--
cyeoh at au.ibm.com<mailto:cyeoh at au.ibm.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


_______________________________________________
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


_______________________________________________
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/20121218/43f36adb/attachment.html>