<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; ">
I've been saying this for a while, but I think OpenGL does a very good job from a documentation perspective.
<div><br>
</div>
<div>They document the core: <a href="http://www.opengl.org/registry/#apispecs">http://www.opengl.org/registry/#apispecs</a></div>
<div>and then provide a list of possible extensions, in an extension registry: <a href="http://www.opengl.org/registry/#arbextspecs">http://www.opengl.org/registry/#arbextspecs</a></div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>Anyway, I think we just need to educate our customers on what extensions are and how they work.</div>
<div><br>
</div>
<div>-jOrGe W.</div>
<div><br>
</div>
<div><br>
<div>
<div>On Dec 18, 2012, at 5:00 PM, Matt Dietz wrote:</div>
<br class="Apple-interchange-newline">
<blockquote type="cite">
<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>That's quite the skew. :-\</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>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</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:anne@openstack.org">anne@openstack.org</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>Tuesday, December 18, 2012 4:42 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] Novaclient and Extensions<br>
</div>
<div><br>
</div>
<div>
<div><br>
<div class="gmail_extra">
<div class="gmail_quote">On Tue, Dec 18, 2012 at 1:26 PM, Matt Dietz <span dir="ltr">
<<a href="mailto:matt.dietz@rackspace.com" target="_blank">matt.dietz@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex" type="cite">
<div style="font-size:14px;font-family:Calibri,sans-serif;word-wrap:break-word">
<div>I agree with this</div>
<div><br>
</div>
<div>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. </div>
<div><br>
</div>
</div>
</blockquote>
<div><br>
Thinking about this, and what it really might look like to a user. I want to apply some hard data around this issue.<br>
<br>
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. <br>
<br>
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.<br>
<br>
What can we do beyond docs?<br>
<br>
Thanks,<br>
Anne<br>
<br>
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.
<br>
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
<a href="https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdExERVZ0elAtc1pWcGtfQWNlMEFNd1E">
https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdExERVZ0elAtc1pWcGtfQWNlMEFNd1E</a> for counts.<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex" type="cite">
<div style="font-size:14px;font-family:Calibri,sans-serif;word-wrap:break-word">
<div></div>
<span>
<div style="padding:3pt 0in 0in;text-align:left;font-size:11pt;border-width:1pt medium medium;border-style:solid none none;border-color:rgb(181,196,223) -moz-use-text-color -moz-use-text-color;font-family:Calibri">
<span style="font-weight:bold">From: </span>Craig Vyvial <<a href="mailto:cp16net@gmail.com" target="_blank">cp16net@gmail.com</a>>
<div class="im"><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>
</div>
<span style="font-weight:bold">Date: </span>Tuesday, December 18, 2012 1:14 PM
<div class="im"><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>
</div>
<div class="im"><span style="font-weight:bold">Subject: </span>Re: [openstack-dev] Novaclient and Extensions<br>
</div>
</div>
<div>
<div class="h5">
<div><br>
</div>
<div>
<div>
<div dir="ltr">Ok i agree that the user should only have to know 1 thing. The entry point.
<div><br>
</div>
<div>Then the discovery of extensions by the client should be api driven by the cloud entry point.</div>
</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Tue, Dec 18, 2012 at 6:03 AM, Christopher Yeoh <span dir="ltr">
<<a href="mailto:cyeoh@au1.ibm.com" target="_blank">cyeoh@au1.ibm.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex" type="cite">
<div>On Mon, 17 Dec 2012 22:37:50 -0800<br>
Monty Taylor <<a href="mailto:mordred@inaugust.com" target="_blank">mordred@inaugust.com</a>> wrote:<br>
<br>
> On 12/17/2012 10:20 PM, Craig Vyvial wrote:<br>
> > I do not think making the client "smart" enough to be able to tell<br>
> > which extensions are available is the right approach. It seems like<br>
> > overkill for the client's responsibility.<br>
> ><br>
> > I maybe reading in to this to far but it seems like if you want to<br>
> > install or enable an extension you should have to install to enable<br>
> > it... aka install python-novaclient-security-groups.<br>
> > Then each extension can be updated maintained separately.<br>
> ><br>
> > But i guess the main draw back I see with this is that then its a<br>
> > pain to "test" this functionality between extensions and core code.<br>
> > But I am sure people/companies have their own custom extensions that<br>
> > have never made it into the core code or never will have already<br>
> > felt some of these pains.<br>
><br>
> Obviously, I agree with Vish here ... but I think that one of the<br>
> places where you and I may be missing each other is in who the<br>
> audience is we are talking about.<br>
><br>
> When you say "if you want to install..." that implies a level of<br>
> agency or understanding that I do not think we should expect from a<br>
> public cloud user. Why would I, as a consumer of an OpenStack based<br>
> public cloud ever "want" to install a novaclient extension module?<br>
> How would I even know I want to do that?<br>
<br>
</div>
+1<br>
<br>
Most users would not know that they have to install an extension<br>
and just finding out which extensions they should install would be<br>
difficult for new and inexperienced users. They'd probably just assume<br>
that the functionality they want is not available.<br>
<br>
So I agree we want the client to automatically detect what<br>
extension capabilities can be used. Perhaps even an easy way for them<br>
to see what functionality they could have from nova client if the<br>
corresponding server side support was installed.<br>
<br>
Chris<br>
<span><font color="#888888">--<br>
<a href="mailto:cyeoh@au.ibm.com" target="_blank">cyeoh@au.ibm.com</a><br>
</font></span>
<div>
<div><br>
<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>
</div>
</div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div>
</div>
</span></div>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">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>
</div>
</div>
</div>
</span></div>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev<br>
</blockquote>
</div>
<br>
</div>
</body>
</html>