Open Stack

On 12/18/2012 03:29 PM, Jorge Williams wrote:
> 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.

/me cries and throws things and product guys...

> 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
> 
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>