Open Stack

> From: Ronald Bradford [mailto:me at ronaldbradford.com] 
> Sent: Wednesday, January 20, 2016 6:34 PM
> To: OpenStack Development Mailing List (not for usage questions)
> Subject: Re: [openstack-dev] [Oslo] Improving deprecated options identification and documentation
>
> Markus,
>
> 
>> Yes, in what release it is to be removed, e.g. Mitaka.  So when is
>> that release cycle, i.e. now once removed there is no record.
>
> The information at which point in time a removal will happen can be
> derived from a combination of:
> * the "Deprecation Notes" (e.g. Nova's at [1]) and
> * the "follows_standard_deprecation" policy [2].
> I don't see the immediate need to duplicate that information.
>
> The potential duplication you refer to enables code scanning/automation to detect and even initiate steps at the start of a release cycle to remove deprecated options.
> Looking at documented notes is a more inconsistent manual approach. The number of deprecated options should not be high, I do not see the issue in ensuring this information is in code as well as docs.

Specially thinking about libraries and projects that releases multiple times per cycle something like "Will be removed in the first release after 17.9.2016" rather than "Will be removed at X.Y.Z" would be preferred. This way we can ensure the correctness and proper deprecation time without needing to care what releases that project happens to do in between. It's not exactly the easiest job to predict all the changes going for months ahead so that specific release can be identified when the deprecation happens.

Apart from that I'm happily behind the proposal of documenting the deprecations better.

- Erno
>
>
> I agree that there should be an explanation in ``deprecation_reason``
> if ``deprecated_for_removal=True`` **why** we deprecated it and which
> follow up actions seem to be reasonable for the ops.
>
> Thanks!  I think for now, stating a reason, stating what release it was deprecated and what release it should be removed provides a starting point with a low barrier of entry to see results.
>
> Ronald (rbradfor)
>
> 
> References:
> [1] Nova's current release notes based on "reno"; "Deprecation Notes":
>
> http://docs.openstack.org/releasenotes/nova/unreleased.html#deprecation-notes
> [2] OpenStack governance docs; tag "assert_follows_standard_deprecation":
>
> https://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html
>
> Regards, Markus Zoeller (markus_z)