<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Jun 13, 2014 at 4: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></blockquote><div><br></div><div>Here is a patch to publish this policy.</div><div><br></div><div><a href="https://review.openstack.org/#/c/100335/">https://review.openstack.org/#/c/100335/</a><br>
</div><div><br></div><div>The published results of this file live at: </div><div><br></div><div><a href="http://docs.openstack.org/developer/nova/devref/policies.html">http://docs.openstack.org/developer/nova/devref/policies.html</a><br>
</div><div><br></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">
<br>
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>
<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>