Open Stack

On Tue, Apr 1, 2014 at 7:40 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> 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]
>

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 at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
> _______________________________________________
> 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/20140402/cc87deb9/attachment.html>