Open Stack

On 03/26/2014 06:30 AM, Thierry Carrez 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.
> 
> If step 4 is blocked, project should first raise the issue at
> cross-project meetings, and if all else fails at the TC level.
> 

I think you did a very nice job of capturing the ideal steps here.
Totally agreed.

-- 
Russell Bryant