<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Jun 13, 2014 at 6:18 AM, Christopher Yeoh <span dir="ltr"><<a href="mailto:cbkyeoh@gmail.com" target="_blank">cbkyeoh@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi Phil,<br>
<div class=""><br>
On Fri, 13 Jun 2014 09:28:30 +0000<br>
"Day, Phil" <<a href="mailto:philip.day@hp.com">philip.day@hp.com</a>> wrote:<br>
><br>
> >The documentation is NOT the canonical source for the behaviour of<br>
> >the API, currently the code should be seen as the reference. We've<br>
> >run into issues before where people have tried to align code to the<br>
> >fit the documentation and made backwards incompatible changes<br>
> >(although this is not one).<br>
><br>
> I’ve never seen this defined before – is this published as official<br>
> Openstack or Nova policy ?<br>
<br>
</div>Its not published, but not following this guideline has got us into<br>
trouble before because we end up making backwards incompatible changes<br>
to force the code to match the docs rather than the other way around.<br>
<br></blockquote><div><br></div><div>At last week's TC meeting we discussed publishing an API Style Guide to supplement <span style="color:rgb(0,0,0);white-space:pre-wrap"><a href="https://wiki.openstack.org/wiki/APIChangeGuidelines">https://wiki.openstack.org/wiki/APIChangeGuidelines</a></span></div>
<div><span style="color:rgb(0,0,0);white-space:pre-wrap"><br></span></div><div><span style="color:rgb(0,0,0);white-space:pre-wrap">Diane Fleming, Mark McClain, and I are starting that. Read the TC take on it at </span><font color="#000000"><span style="white-space:pre-wrap"><a href="http://eavesdrop.openstack.org/meetings/tc/2014/tc.2014-06-10-20.03.log.html">http://eavesdrop.openstack.org/meetings/tc/2014/tc.2014-06-10-20.03.log.html</a></span></font></div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
The documentation historically has been generated manually by people<br>
looking at the code and writing up what they think it does. NOTE: this<br>
is not a reflection on the docs team - they have done an EXCELLENT job<br>
based on what we've been giving them (just the api samples and the<br>
code). Its very easy to get it wrong and its most often someone who has<br>
not written the code who is writing the documentation and not familiar<br>
with what was actually merged.<br></blockquote><div><br></div><div><br></div><div>Yes, Diane does an amazing job with this task. We I haven't identified others dedicated mostly to API docs across all of OpenStack. That said, the Nova team does a good job identifying pro-level API writers to help with their API docs. </div>
<div><br></div><div>There are 65 Compute API doc bugs and my sense is this is an indicator and accurately reflects what's wrong in both the v2 and v3 (2.1) docs. </div><div><a href="http://bit.ly/compute-api-bugs">http://bit.ly/compute-api-bugs</a><br>
</div><div><br></div><div>Assign yourself and ask anyone on the docs team if you need assistance through IRC on #openstack-doc or the mailing list <a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>. </div>
<div><br></div><div>Before you complain about WADL, please let me know if you have another solution for documenting extensible APIs and are interested in implementing it across all the project's APIs. Not being snarky at all with that request, just letting everyone know that our findings were "what isn't broke do not fix" and "leave the docs to the doc pros" at the Summit. Would love to find another solution but the one we have does the job. </div>
<div><br></div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class=""><br>
> Personally I think we should be putting as much effort into reviewing<br>
> the API docs as we do API code so that we can say that the API docs<br>
> are the canonical source for behavior. Not being able to fix bugs<br>
> in say input validation that escape code reviews because they break<br>
> backwards compatibility seems to be a weakness to me.<br>
<br>
</div>+1 for people to go back through the v2 api docs and fix the<br>
documentation where it is incorrect.<br>
<br>
So our medium term goal (and this one the reasons behind wanting the<br>
new v2.1/v3 infrastructure with json schema etc) is to be able to<br>
properly automate the production of the documentation from the code. So<br>
there is no contradiction between the two.<br>
<br>
I agree we need to be able to fix bugs that result in backwards<br>
incompatible changes. v2.1microversions should allow us to do that<br>
cleanly as possible.<br>
<br>
Chris<br>
<div class=""><br>
><br>
><br>
> Phil<br>
><br>
><br>
><br>
> From: Christopher Yeoh [mailto:<a href="mailto:cbkyeoh@gmail.com">cbkyeoh@gmail.com</a>]<br>
> Sent: 13 June 2014 04:00<br>
> To: OpenStack Development Mailing List (not for usage questions)<br>
> Subject: Re: [openstack-dev] [Nova] Review guidelines for API patches<br>
><br>
> On Fri, Jun 13, 2014 at 11:28 AM, Matt Riedemann<br>
</div><div class="">> <<a href="mailto:mriedem@linux.vnet.ibm.com">mriedem@linux.vnet.ibm.com</a><mailto:<a href="mailto:mriedem@linux.vnet.ibm.com">mriedem@linux.vnet.ibm.com</a>>> wrote:<br>
><br>
><br>
> On 6/12/2014 5:58 PM, Christopher Yeoh wrote:<br>
> On Fri, Jun 13, 2014 at 8:06 AM, Michael Still<br>
> <<a href="mailto:mikal@stillhq.com">mikal@stillhq.com</a><mailto:<a href="mailto:mikal@stillhq.com">mikal@stillhq.com</a>><br>
</div><div class="">> <mailto:<a href="mailto:mikal@stillhq.com">mikal@stillhq.com</a><mailto:<a href="mailto:mikal@stillhq.com">mikal@stillhq.com</a>>>> wrote:<br>
><br>
> In light of the recent excitement around quota classes and the<br>
> floating ip pollster, I think we should have a conversation about<br>
> the review guidelines we'd like to see for API changes proposed<br>
> against nova. My initial proposal is:<br>
><br>
> - API changes should have an associated spec<br>
><br>
><br>
> +1<br>
><br>
> - API changes should not be merged until there is a tempest<br>
> change to test them queued for review in the tempest repo<br>
><br>
><br>
> +1<br>
><br>
> Chris<br>
><br>
> _______________________________________________<br>
> OpenStack-dev mailing list<br>
</div>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><mailto:<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>><br>
<div><div class="h5">> <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>
> We do have some API change guidelines here [1]. I don't want to go<br>
> overboard on every change and require a spec if it's not necessary,<br>
> i.e. if it falls into the 'generally ok' list in that wiki. But if<br>
> it's something that's not documented as a supported API (so it's<br>
> completely new) and is pervasive (going into novaclient so it can be<br>
> used in some other service), then I think that warrants some spec<br>
> consideration so we don't miss something.<br>
><br>
> To compare, this [2] is an example of something that is updating an<br>
> existing API but I don't think warrants a blueprint since I think it<br>
> falls into the 'generally ok' section of the API change guidelines.<br>
><br>
> So really I see this a new feature, not a bug fix. Someone thought<br>
> that detail was supported when writing the documentation but it never<br>
> was. The documentation is NOT the canonical source for the behaviour<br>
> of the API, currently the code should be seen as the reference. We've<br>
> run into issues before where people have tried to align code to the<br>
> fit the documentation and made backwards incompatible changes<br>
> (although this is not one).<br>
><br>
> Perhaps we need a streamlined queue for very simple API changes, but<br>
> I do think API changes should get more than the usual review because<br>
> we have to live with them for so long (short of an emergency revert<br>
> if we catch it in time).<br>
><br>
> [1] <a href="https://wiki.openstack.org/wiki/APIChangeGuidelines" target="_blank">https://wiki.openstack.org/wiki/APIChangeGuidelines</a><br>
> [2] <a href="https://review.openstack.org/#/c/99443/" target="_blank">https://review.openstack.org/#/c/99443/</a><br>
><br>
> --<br>
><br>
> Thanks,<br>
><br>
> Matt Riedemann<br>
><br>
><br>
><br>
> _______________________________________________<br>
> OpenStack-dev mailing list<br>
</div></div>> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><mailto:<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>
<div class=""><div class="h5">><br>
<br>
<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>
</div></div></blockquote></div><br></div></div>