Open Stack

On Sun, 07 Jul 2013 09:39:28 +1000
Tom Fifield <tom at openstack.org> wrote:

> On 06/07/13 23:16, Anne Gentle wrote:
> > On Sat, Jul 6, 2013 at 5:41 AM, Tom Fifield <tom at openstack.org
> > 
> > 
> > Incompleteness for Compute? Or is it that Identity v2 and v2 are in
> > the process of being added? Or? Anything else missing? Need bug
> > references. :)
> 
> As you know, I'm a fan of the "bugs or it isn't true" response too :)
> However, in this case, since we're publishing the definitive reference
> on something that can actually be tested to be complete - we should
> have higher standards. Right now, the truth is, we have no idea how
> complete the API reference is. The only way we have to find out is to
> sit down with a beverage of some description and methodically work
> through a ton of code and a ton of WADL.
> 
> I guess Grizzly was our first attempt at tracking these, with
> DocImpact, and the fact that there are still 14 of those bugs unfixed
> (yes, including one for compute API - #1084500) means we are
> incomplete :)
> https://launchpad.net/openstack-api-site/+milestone/grizzly

I am guilty of not always submitting doc bug report when I should have,
though I hope I'm getting better at it. When doing the V3 extension
ports I did notice at least once that API docs did not appear to exist
for an extension (but unfortunately can't remember which one that is
now!).

I think that the reviews in Nova have improved over the last year where
if API samples are not included changesets will get -1'd. Missing
docimpact flag not so much. If we can get to the point where
to update the API documentation someone just needs to run a script and
new APIs would automatically be included then it would greatly reduce
the chance of APIs being accidentally omitted.

I don't think we'll have the resources to fix this for V2 and so that
probably needs an audit at some point, but I'm really hoping we can do
something better for V3.

Chris