<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=us-ascii">
<meta name="Generator" content="Microsoft Word 12 (filtered medium)">
<!--[if !mso]><style>v\:* {behavior:url(#default#VML);}
o\:* {behavior:url(#default#VML);}
w\:* {behavior:url(#default#VML);}
.shape {behavior:url(#default#VML);}
</style><![endif]--><style><!--
/* Font Definitions */
@font-face
{font-family:SimSun;
panose-1:2 1 6 0 3 1 1 1 1 1;}
@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;}
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
@font-face
{font-family:"\@SimSun";
panose-1:2 1 6 0 3 1 1 1 1 1;}
@font-face
{font-family:Verdana;
panose-1:2 11 6 4 3 5 4 4 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;}
p
{mso-style-priority:99;
mso-margin-top-alt:auto;
margin-right:0cm;
mso-margin-bottom-alt:auto;
margin-left:0cm;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
tt
{mso-style-priority:99;
font-family:"Courier New";}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0cm;
margin-right:0cm;
margin-bottom:0cm;
margin-left:36.0pt;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@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-CA" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Here is the guideline to evaluate an API change:
<a href="http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_changes.html">
http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_changes.html</a> . In particular, I highlight the followings:<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">The following types of changes are acceptable when conditionally added as a new API extension:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">* Adding an optional property to a resource representation which may be supplied by clients, assuming the API previously would ignore this property.<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">The following types of changes are generally not considered acceptable:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">* A change such that a request which was successful before now results in an error response<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">* Changing the semantics of a property in a resource representation which may be supplied by clients.<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>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Above all, as Ton mentioned, just adding a new option (--rollback) looks OK. However, the implementation should not break the existing behaviors. In particular,
the proposed patch (<a href="https://review.openstack.org/#/c/343478/4/magnum/api/controllers/v1/bay.py">https://review.openstack.org/#/c/343478/4/magnum/api/controllers/v1/bay.py</a>) changes the request parameters and their types, which is considered to
be unacceptable (unless bumping the microversion). To deal with that, I think there are two options:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">1. Modify the proposed patch to make it backward-compatible. In particular, it should keep the existing properties as is (don’t change their types and semantics).
The new option should be optional and it should be ignored if clients are sending the old requests.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">2. Keep the proposed patch as is, but bumping the microversion. You need to wait for this patch [1] to merge, and reference the microversion guide [1] to bump
the version. In addition, it is highly recommended to follow the standard deprecation policy [2]. That means i) print a deprecated warning if old APIs are used, ii) document how to migrate from old APIs to new APIs, and iii) remove the old APIs after the deprecation
period.<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">[1]
<a href="https://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html">
https://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html</a><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">[2]
<a href="https://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html">
https://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html</a><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">Best regards,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Hongbin<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 #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span lang="EN-US" style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span lang="EN-US" style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> Ton Ngo [mailto:ton@us.ibm.com]
<br>
<b>Sent:</b> July-27-16 9:36 AM<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Subject:</b> Re: [openstack-dev] [magnum] Support for bay rollback may break magnum API backward compatibility<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p>Hi Wenzhi,<br>
Looks like you are adding the new --rollback option to bay-update. If the user does not specify this new option,
<br>
then bay-update behaves the same as before; in other words, if it fails, then the state of the bay will be left<br>
in the partially updated mode. Is this correct? If so, this does change the API, but does not seem to break
<br>
backward compatibility.<br>
Ton Ngo,<br>
<br>
<img border="0" width="16" height="16" id="_x0000_i1079" src="cid:image001.gif@01D1E81A.F1E6E610" alt="Inactive hide details for "Wenzhi Yu (yuywz)" ---07/27/2016 04:13:07 AM---Hi folks, I am working on a patch [1] to add bay roll"><span style="color:#424282">"Wenzhi
Yu (yuywz)" ---07/27/2016 04:13:07 AM---Hi folks, I am working on a patch [1] to add bay rollback machanism on update failure. But it seems</span><br>
<br>
<span style="font-size:10.0pt;color:#5F5F5F">From: </span><span style="font-size:10.0pt">"Wenzhi Yu (yuywz)" <<a href="mailto:wenzhi_yu@163.com">wenzhi_yu@163.com</a>></span><br>
<span style="font-size:10.0pt;color:#5F5F5F">To: </span><span style="font-size:10.0pt">"openstack-dev" <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>></span><br>
<span style="font-size:10.0pt;color:#5F5F5F">Date: </span><span style="font-size:10.0pt">07/27/2016 04:13 AM</span><br>
<span style="font-size:10.0pt;color:#5F5F5F">Subject: </span><span style="font-size:10.0pt">[openstack-dev] [magnum] Support for bay rollback may break magnum API backward compatibility</span><o:p></o:p></p>
<div class="MsoNormal">
<hr size="2" width="100%" noshade="" style="color:#8091A5" align="left">
</div>
<p class="MsoNormal"><br>
<br>
<br>
<span style="font-size:13.5pt">Hi folks,</span><br>
<br>
<span style="font-size:13.5pt">I am working on a patch [1] to add bay rollback machanism on update failure. But it seems to break magnum API</span><br>
<span style="font-size:13.5pt">backward compatibility.</span><br>
<br>
<span style="font-size:13.5pt;color:#000011">I'm not sure how to deal with this, can you please give me your suggestion? Thanks!</span><br>
<br>
<span style="font-size:13.5pt;color:#000011">[1]<a href="https://review.openstack.org/#/c/343478/">https://review.openstack.org/#/c/343478/</a></span><br>
<br>
<span style="font-family:"Verdana","sans-serif";color:silver">2016-07-27</span><o:p></o:p></p>
<div class="MsoNormal">
<hr size="2" width="100%" align="left">
</div>
<p class="MsoNormal" style="margin-bottom:12.0pt"><br>
<span style="font-family:"Verdana","sans-serif";color:silver">Best Regards,</span><br>
<span style="font-family:"Verdana","sans-serif";color:silver">Wenzhi Yu (yuywz)</span><tt><span style="font-size:10.0pt">__________________________________________________________________________</span></tt><span style="font-size:10.0pt;font-family:"Courier New""><br>
<tt>OpenStack Development Mailing List (not for usage questions)</tt><br>
<tt>Unsubscribe: <a href="mailto:OpenStack-dev-request@lists.openstack.org?subject:unsubscribe">
OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a></tt><br>
<tt><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a></tt><br>
</span><br>
<br>
<o:p></o:p></p>
</div>
</div>
</body>
</html>