<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Apr 1, 2014 at 7:40 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</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"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">
<div><div class="h5">On Wed, Mar 26, 2014 at 5:30 AM, Thierry Carrez <span dir="ltr"><<a href="mailto:thierry@openstack.org" target="_blank">thierry@openstack.org</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">Russell Bryant wrote:<br>
> [...]<br>
<div>> First, it seems there isn't a common use of "deprecated". To me,<br>
> marking something deprecated means that the deprecated feature:<br>
><br>
> - has been completely replaced by something else<br>
><br>
> - end users / deployers should take action to migrate to the<br>
> new thing immediately.<br>
><br>
> - The project has provided a documented migration path<br>
><br>
> - the old thing will be removed at a specific date/release<br>
<br>
</div>Agreed, IMHO we need to reserve the use the "deprecated" terminology for<br>
the idea of moving end users, deployers, external client library<br>
developers (people outside of OpenStack direct reach) off a given API<br>
version. Deprecation is about giving them a fair heads-up about<br>
something that is about to be removed, so that they are encouraged to<br>
move off it. It needs to be discussed and announced with the user<br>
community, and come with a precise plan.<br>
<br>
Internal consumption of APIs between OpenStack projects is a different<br>
beast: (1) it's under our control and (2) we really can't remove an API<br>
until all our internal pieces have migrated off it.<br>
<br>
So I wouldn't use "deprecation warnings" to encourage other OpenStack<br>
projects to move off an API. They can't come with a precise date since<br>
if projects don't comply with this "suggestion" we just can't remove<br>
that API support. I would therefore go this way:<br>
<br>
1. API vN is stable and supported<br>
2. API vN+1 is being developed and experimental<br>
3. API vN+1 is marked stable and supported<br>
4. Engage with other consuming OpenStack projects to migrate to vN+1<br>
5. Migration is completed<br>
6. Deprecation plan (and removal date) is discussed with stakeholders<br>
7. Deprecation plan (and removal date) is decided and announced<br>
8. Deprecation messages are added to code for API vN users<br>
9. At removal date, API vN is removed<br>
<br>
Keystone is at step 4. It shouldn't use "deprecation" terminology before<br>
step 6.<br></blockquote><div><br></div></div></div><div><div>Hi all, I wanted to double-check some wording. I'm chasing down how to update docs based on a DocImpact flag[1] with related bugs and the nova blueprint to deprecate XML. [2] I'm pretty sure "deprecate" is the term we're using as the message says "XML support has been deprecated and will be removed in the Juno release." [3] </div>
</div></div></div></div></blockquote><div><br></div><div>I don't see any issue with using the term "deprecate" here. However, I think it's important to say it "may" be removed, not "will." Deprecations are frequently delayed, so the wording has potential to be inaccurate as-is. You could even go so far as to say "it *may* be removed *as early as* the Juno release." Oslo's deprecation decorator (the "deprecator") does not use the wording today, though.</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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div>
<div><br></div><div>To me, the same arguments that caused a different message to be substituted for Keystone's v2.0 API could be used here. Is that inaccurate? Has the discussion been carried to the logical conclusion? Should "deprecated" be used yet?</div>
</div></div></div></div></blockquote><div><br></div><div>I just want to point out that Keystone followed Nova's lead on this one - Keystone's XML support, which is only rigorously tested against a very small portion of the v2 API, is deprecated as of Icehouse as well. I think XML is a broader community issue, not one that needs to be discussed per-project.</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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div>
</div><div><br></div><div>I think we could follow a similar pattern for XML in the Compute API v2 -- we need to define "discussed with stakeholders" and how/when we say the discussion is done. I wanted to put up a set of ideas for the channels (push) and inputs (pull):</div>
<div>- posted a collaborative statement expressing need to deprecate to the openstack-dev mailing list </div></div></div></div></blockquote><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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>- posted a request for comment to the openstack mailing list</div></div></div></div></blockquote><div><br></div><div>In the case of XML, I think we already have a sufficiently long history of relevant mailing list discussions suggesting a focus on a single serialization format (JSON, in our case).<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"><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div>- questions added to the user survey that indicate amount of use and desire to move away from</div>
<div>- responses to user survey compiled showing a certain percent of agreement on deprecation</div></div></div></div></blockquote><div><br></div><div>This would be really interesting to see, at least for XML. I wouldn't recommend it for all the smaller features that face deprecation each release.</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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div><br></div><div>Would that be sufficient for the "discussed with stakeholders" step? Any other channels I'm missing? If the discussion requires six months of discussion at a minimum, is that acceptable?</div>
</div></div></div></blockquote><div><br></div><div><div>One of keystone's summit sessions in Hong Kong partly focused on producing a list of things to deprecate during Icehouse. We ended up deprecating things that there was a clear consensus on (redundant middleware, etc). Although there were certainly deployers represented in that session, I like the idea of making deprecations a regular topic in a project-specific design session focused on collecting deployer feedback (using the session format suggested in a recent openstack-dev thread for Atlanta).<br>
</div></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 dir="ltr"><div class="gmail_extra">
<div class="gmail_quote">
<div><br></div><div>Thanks,<br>Anne</div><div><br></div><div>[1] <a href="https://bugs.launchpad.net/openstack-manuals/+bug/1283341" target="_blank">https://bugs.launchpad.net/openstack-manuals/+bug/1283341</a><br></div>
<div>
[2] <a href="https://blueprints.launchpad.net/nova/+spec/deprecate-xml-in-v2-api" target="_blank">https://blueprints.launchpad.net/nova/+spec/deprecate-xml-in-v2-api</a></div>
<div>[3] <a href="https://review.openstack.org/#/c/75439/2/nova/api/openstack/compute/servers.py" target="_blank">https://review.openstack.org/#/c/75439/2/nova/api/openstack/compute/servers.py</a> </div><div class=""><div>
<br></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>
If step 4 is blocked, project should first raise the issue at<br>
cross-project meetings, and if all else fails at the TC level.<br>
<span><font color="#888888"><br>
--<br>
Thierry Carrez (ttx)<br>
</font></span><div><div><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><br>
</div></div></blockquote></div></div><br></div></div>
<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>
<br></blockquote></div><br></div></div>