On Wed, Mar 26, 2014 at 5:30 AM, Thierry Carrez <[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] 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 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 - 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 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? 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 > [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
