<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.hoenzb
{mso-style-name:hoenzb;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri","sans-serif";}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Hi Chris,<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">>The documentation is NOT the canonical source for the behaviour of the API, currently the code should be seen as the reference. We've run into issues before where people have tried to align code to the fit the documentation and made backwards
incompatible changes (although this is not one).<o:p></o:p></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">I’ve never seen this defined before – is this published as official Openstack or Nova policy ?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Personally I think we should be putting as much effort into reviewing the API docs as we do API code so that we can say that the API docs are the canonical
source for behavior. Not being able to fix bugs in say input validation that escape code reviews because they break backwards compatibility seems to be a weakness to me.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Phil<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0cm 0cm 0cm 4.0pt">
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span style="font-size:11.0pt;font-family:"Calibri","sans-serif"">From:</span></b><span style="font-size:11.0pt;font-family:"Calibri","sans-serif""> Christopher Yeoh [mailto:cbkyeoh@gmail.com]
<br>
<b>Sent:</b> 13 June 2014 04:00<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Subject:</b> Re: [openstack-dev] [Nova] Review guidelines for API patches<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div>
<div>
<p class="MsoNormal">On Fri, Jun 13, 2014 at 11:28 AM, Matt Riedemann <<a href="mailto:mriedem@linux.vnet.ibm.com" target="_blank">mriedem@linux.vnet.ibm.com</a>> wrote:<o:p></o:p></p>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm">
<div>
<p class="MsoNormal"><br>
<br>
On 6/12/2014 5:58 PM, Christopher Yeoh wrote:<o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm">
<div>
<p class="MsoNormal">On Fri, Jun 13, 2014 at 8:06 AM, Michael Still <<a href="mailto:mikal@stillhq.com" target="_blank">mikal@stillhq.com</a><o:p></o:p></p>
</div>
<div>
<div>
<p class="MsoNormal" style="margin-bottom:12.0pt"><mailto:<a href="mailto:mikal@stillhq.com" target="_blank">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 the<br>
review guidelines we'd like to see for API changes proposed against<br>
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 change to<br>
test them queued for review in the tempest repo<br>
<br>
<br>
+1<br>
<br>
Chris<br>
<br>
<o:p></o:p></p>
</div>
</div>
<div>
<p class="MsoNormal" style="margin-bottom:12.0pt">_______________________________________________<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><o:p></o:p></p>
</div>
</blockquote>
<p class="MsoNormal" style="margin-bottom:12.0pt"><br>
We do have some API change guidelines here [1]. I don't want to go overboard on every change and require a spec if it's not necessary, i.e. if it falls into the 'generally ok' list in that wiki. But if it's something that's not documented as a supported API
(so it's completely new) and is pervasive (going into novaclient so it can be used in some other service), then I think that warrants some spec consideration so we don't miss something.<br>
<br>
To compare, this [2] is an example of something that is updating an existing API but I don't think warrants a blueprint since I think it falls into the 'generally ok' section of the API change guidelines.<o:p></o:p></p>
</blockquote>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">So really I see this a new feature, not a bug fix. Someone thought that detail was supported when writing the documentation but it never was. The documentation is NOT the canonical source for the behaviour of the API, currently the code
should be seen as the reference. We've run into issues before where people have tried to align code to the fit the documentation and made backwards incompatible changes (although this is not one).<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Perhaps we need a streamlined queue for very simple API changes, but I do think API changes should get more than the usual review because we have to live with them for so long (short of an emergency revert if we catch it in time).<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm">
<p class="MsoNormal">[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><span style="color:#888888"><br>
<br>
<span class="hoenzb">-- </span><br>
<br>
<span class="hoenzb">Thanks,</span><br>
<br>
<span class="hoenzb">Matt Riedemann</span></span><o:p></o:p></p>
<div>
<div>
<p class="MsoNormal"><br>
<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><o:p></o:p></p>
</div>
</div>
</blockquote>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</div>
</div>
</div>
</body>
</html>