On Tue, Apr 1, 2014 at 7:40 PM, Anne Gentle <a...@openstack.org> wrote:
> > > > On Wed, Mar 26, 2014 at 5:30 AM, Thierry Carrez <thie...@openstack.org>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. > > 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. > > 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). > - 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. > > 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). > > Thanks, > Anne > > [1] https://bugs.launchpad.net/openstack-manuals/+bug/1283341 > [2] https://blueprints.launchpad.net/nova/+spec/deprecate-xml-in-v2-api > [3] > https://review.openstack.org/#/c/75439/2/nova/api/openstack/compute/servers.py > > > >> If step 4 is blocked, project should first raise the issue at >> cross-project meetings, and if all else fails at the TC level. >> >> -- >> Thierry Carrez (ttx) >> >> _______________________________________________ >> OpenStack-dev mailing list >> OpenStack-dev@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev