Open Stack

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

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
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140401/645583d0/attachment.html>