<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Apr 2, 2014 at 8:43 AM, Russell Bryant <span dir="ltr"><<a href="mailto:rbryant@redhat.com" target="_blank">rbryant@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="">On 04/02/2014 09:20 AM, Dolph Mathews wrote:<br>
><br>
> On Tue, Apr 1, 2014 at 7:40 PM, Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a><br>
</div><div class="">> <mailto:<a href="mailto:anne@openstack.org">anne@openstack.org</a>>> wrote:<br>
><br>
><br>
><br>
><br>
> On Wed, Mar 26, 2014 at 5:30 AM, Thierry Carrez<br>
</div><div><div class="h5">> <<a href="mailto:thierry@openstack.org">thierry@openstack.org</a> <mailto:<a href="mailto:thierry@openstack.org">thierry@openstack.org</a>>> wrote:<br>
><br>
> Russell Bryant wrote:<br>
> > [...]<br>
> > 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>
> Agreed, IMHO we need to reserve the use the "deprecated"<br>
> terminology for<br>
> the idea of moving end users, deployers, external client library<br>
> developers (people outside of OpenStack direct reach) off a<br>
> 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<br>
> 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<br>
> different<br>
> beast: (1) it's under our control and (2) we really can't remove<br>
> an API<br>
> until all our internal pieces have migrated off it.<br>
><br>
> So I wouldn't use "deprecation warnings" to encourage other<br>
> OpenStack<br>
> projects to move off an API. They can't come with a precise date<br>
> 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<br>
> 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"<br>
> terminology before<br>
> step 6.<br>
><br>
><br>
> Hi all, I wanted to double-check some wording. I'm chasing down how<br>
> to update docs based on a DocImpact flag[1] with related bugs and<br>
> the nova blueprint to deprecate XML. [2] I'm pretty sure "deprecate"<br>
> is the term we're using as the message says "XML support has been<br>
> deprecated and will be removed in the Juno release." [3]<br>
><br>
><br>
> I don't see any issue with using the term "deprecate" here. However, I<br>
> think it's important to say it "may" be removed, not "will."<br>
> Deprecations are frequently delayed, so the wording has potential to be<br>
> inaccurate as-is. You could even go so far as to say "it *may* be<br>
> removed *as early as* the Juno release." Oslo's deprecation decorator<br>
> (the "deprecator") does not use the wording today, though.<br>
<br>
</div></div>Agree that the wording should be changed.<br>
<br>
<a href="https://review.openstack.org/84725" target="_blank">https://review.openstack.org/84725</a><br>
<br>
<a href="https://bugs.launchpad.net/nova/+bug/1301384" target="_blank">https://bugs.launchpad.net/nova/+bug/1301384</a><br>
<br>
I'll get this into icehouse-rc2 for Nova.<br>
<div class=""><br>
><br>
><br>
><br>
> To me, the same arguments that caused a different message to be<br>
> substituted for Keystone's v2.0 API could be used here. Is that<br>
> inaccurate? Has the discussion been carried to the logical<br>
> conclusion? Should "deprecated" be used yet?<br>
><br>
><br>
> I just want to point out that Keystone followed Nova's lead on this one<br>
> - Keystone's XML support, which is only rigorously tested against a very<br>
> small portion of the v2 API, is deprecated as of Icehouse as well. I<br>
> think XML is a broader community issue, not one that needs to be<br>
> discussed per-project.<br>
<br>
</div>In terms of the the project-wide issue, the TC at least formalized that<br>
the only thing we expect from a project is a REST API with JSON support.<br>
We didn't want to *prevent* XML support.<br>
<br>
<a href="http://git.openstack.org/cgit/openstack/governance/tree/reference/incubation-integration-requirements#n40" target="_blank">http://git.openstack.org/cgit/openstack/governance/tree/reference/incubation-integration-requirements#n40</a><br>
<br>
"Project must have a REST API with at least a JSON entity representation"<br>
<div class=""><br>
> I think we could follow a similar pattern for XML in the Compute API<br>
> v2 -- we need to define "discussed with stakeholders" and how/when<br>
> we say the discussion is done. I wanted to put up a set of ideas for<br>
> the channels (push) and inputs (pull):<br>
> - posted a collaborative statement expressing need to deprecate to<br>
> the openstack-dev mailing list<br>
><br>
> - posted a request for comment to the openstack mailing list<br>
><br>
><br>
> In the case of XML, I think we already have a sufficiently long history<br>
> of relevant mailing list discussions suggesting a focus on a single<br>
> serialization format (JSON, in our case).<br>
><br>
<br>
</div>Completely agree here.<br>
<div class=""><br>
> - questions added to the user survey that indicate amount of use and<br>
> desire to move away from<br>
> - responses to user survey compiled showing a certain percent of<br>
> agreement on deprecation<br>
><br>
><br>
> This would be really interesting to see, at least for XML. I wouldn't<br>
> recommend it for all the smaller features that face deprecation each<br>
> release.<br>
<br>
</div>One thing we have in Nova now is a debug log entry that tells you the<br>
content-type for a request. We can now use that to get concrete data.<br>
I've already seen some preliminary numbers on this from Rackspace's<br>
public cloud. This kind of thing is what I'm most interested in to help<br>
drive the finalization of this.<br>
<div class=""><br>
><br>
><br>
> Would that be sufficient for the "discussed with stakeholders" step?<br>
> Any other channels I'm missing? If the discussion requires six<br>
> months of discussion at a minimum, is that acceptable?<br>
><br>
><br>
> One of keystone's summit sessions in Hong Kong partly focused on<br>
> producing a list of things to deprecate during Icehouse. We ended up<br>
> deprecating things that there was a clear consensus on (redundant<br>
> middleware, etc). Although there were certainly deployers represented in<br>
> that session, I like the idea of making deprecations a regular topic in<br>
> a project-specific design session focused on collecting deployer<br>
> feedback (using the session format suggested in a recent openstack-dev<br>
> thread for Atlanta).<br>
<br>
</div>Sessions are great, but shouldn't be the only forum, nor should it be a<br>
place any decisions are actually made, IMO, given that not everyone can<br>
be present. It's one place of many used to gather input before making<br>
an informed decision.<br></blockquote><div><br></div><div>++ I intended to suggest it as a supplementary approach for gathering feedback.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Russell Bryant<br>
</font></span><div class="HOEnZb"><div class="h5"><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>