Open Stack

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.

-- 
Thierry Carrez (ttx)