On Wed, Apr 2, 2014 at 8:43 AM, Russell Bryant <[email protected]> wrote:
> On 04/02/2014 09:20 AM, Dolph Mathews wrote: > > > > On Tue, Apr 1, 2014 at 7:40 PM, Anne Gentle <[email protected] > > <mailto:[email protected]>> wrote: > > > > > > > > > > On Wed, Mar 26, 2014 at 5:30 AM, Thierry Carrez > > <[email protected] <mailto:[email protected]>> wrote: > > > > Russell Bryant wrote: > > > [...] > > > First, it seems there isn't a common use of "deprecated". To > me, > > > marking something deprecated means that the deprecated feature: > > > > > > - has been completely replaced by something else > > > > > > - end users / deployers should take action to migrate to the > > > new thing immediately. > > > > > > - The project has provided a documented migration path > > > > > > - the old thing will be removed at a specific date/release > > > > Agreed, IMHO we need to reserve the use the "deprecated" > > terminology for > > the idea of moving end users, deployers, external client library > > developers (people outside of OpenStack direct reach) off a > > given API > > version. Deprecation is about giving them a fair heads-up about > > something that is about to be removed, so that they are > > encouraged to > > move off it. It needs to be discussed and announced with the user > > community, and come with a precise plan. > > > > Internal consumption of APIs between OpenStack projects is a > > different > > beast: (1) it's under our control and (2) we really can't remove > > an API > > until all our internal pieces have migrated off it. > > > > So I wouldn't use "deprecation warnings" to encourage other > > OpenStack > > projects to move off an API. They can't come with a precise date > > since > > if projects don't comply with this "suggestion" we just can't > remove > > that API support. I would therefore go this way: > > > > 1. API vN is stable and supported > > 2. API vN+1 is being developed and experimental > > 3. API vN+1 is marked stable and supported > > 4. Engage with other consuming OpenStack projects to migrate to > vN+1 > > 5. Migration is completed > > 6. Deprecation plan (and removal date) is discussed with > > stakeholders > > 7. Deprecation plan (and removal date) is decided and announced > > 8. Deprecation messages are added to code for API vN users > > 9. At removal date, API vN is removed > > > > Keystone is at step 4. It shouldn't use "deprecation" > > terminology before > > step 6. > > > > > > 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] > > > > > > 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. > > Agree that the wording should be changed. > > https://review.openstack.org/84725 > > https://bugs.launchpad.net/nova/+bug/1301384 > > I'll get this into icehouse-rc2 for Nova. > > > > > > > > > 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? > > > > > > 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. > > In terms of the the project-wide issue, the TC at least formalized that > the only thing we expect from a project is a REST API with JSON support. > We didn't want to *prevent* XML support. > > > http://git.openstack.org/cgit/openstack/governance/tree/reference/incubation-integration-requirements#n40 > > "Project must have a REST API with at least a JSON entity representation" > > > 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): > > - posted a collaborative statement expressing need to deprecate to > > the openstack-dev mailing list > > > > - posted a request for comment to the openstack mailing list > > > > > > 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). > > > > Completely agree here. > > > - questions added to the user survey that indicate amount of use and > > desire to move away from > > - responses to user survey compiled showing a certain percent of > > agreement on deprecation > > > > > > 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. > > One thing we have in Nova now is a debug log entry that tells you the > content-type for a request. We can now use that to get concrete data. > I've already seen some preliminary numbers on this from Rackspace's > public cloud. This kind of thing is what I'm most interested in to help > drive the finalization of this. > > > > > > > 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? > > > > > > 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). > > Sessions are great, but shouldn't be the only forum, nor should it be a > place any decisions are actually made, IMO, given that not everyone can > be present. It's one place of many used to gather input before making > an informed decision. > ++ I intended to suggest it as a supplementary approach for gathering feedback. > > -- > Russell Bryant > > _______________________________________________ > OpenStack-dev mailing list > [email protected] > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
_______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
