Open Stack

On 04/02/2014 09:20 AM, Dolph Mathews wrote:
> 
> On Tue, Apr 1, 2014 at 7:40 PM, Anne Gentle <anne at openstack.org
> <mailto:anne at openstack.org>> wrote:
> 
> 
> 
> 
>     On Wed, Mar 26, 2014 at 5:30 AM, Thierry Carrez
>     <thierry at openstack.org <mailto: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.

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.

-- 
Russell Bryant