Re: [openstack-dev] [Oslo] Improving deprecated options identification and documentation
> From: Ronald Bradford [mailto:m...@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) __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
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. > 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) > > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Oslo] Improving deprecated options identification and documentation
Ronald Bradford wrote on 01/15/2016 03:04:29 AM: > From: Ronald Bradford > To: "OpenStack Development Mailing List (not for usage questions)" > > Date: 01/15/2016 03:05 AM > Subject: Re: [openstack-dev] [Oslo] Improving deprecated options > identification and documentation > > On Thu, Jan 14, 2016 at 11:58 AM, Jay Pipes wrote: > > On 01/14/2016 11:45 AM, Ronald Bradford wrote: > >> > >> Presently the oslo.config Opt class has the attributes > >> deprecated_for_removal and deprecated_reason [1] > >> > >> I would like to propose that we use deprecated_reason (at a minimum) to > >> detail in what release an option was deprecated in, and what release it > >> is then removed in. > > > > > > You mean what release it *will* be removed in, right? Clearly, once it's > > removed, there won't be any indication it ever existed ;) > > > > 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. 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. 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) > > > > Any improvement in this regard I think would enhance the user experience > > considerably, thank you Ronald for tackling this area. I'd also suggest > > cc'ing (or sending a separate ML post) to the openstack-operators@ ML to > > gather feedback from ops folks. > > > > > will do! > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Oslo] Improving deprecated options identification and documentation
On Thu, Jan 14, 2016 at 11:58 AM, Jay Pipes wrote: > On 01/14/2016 11:45 AM, Ronald Bradford wrote: >> >> Presently the oslo.config Opt class has the attributes >> deprecated_for_removal and deprecated_reason [1] >> >> I would like to propose that we use deprecated_reason (at a minimum) to >> detail in what release an option was deprecated in, and what release it >> is then removed in. > > > You mean what release it *will* be removed in, right? Clearly, once it's > removed, there won't be any indication it ever existed ;) > 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. > > Any improvement in this regard I think would enhance the user experience > considerably, thank you Ronald for tackling this area. I'd also suggest > cc'ing (or sending a separate ML post) to the openstack-operators@ ML to > gather feedback from ops folks. > will do! __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Oslo] Improving deprecated options identification and documentation
Excerpts from Jay Pipes's message of 2016-01-14 11:58:13 -0500: > On 01/14/2016 11:45 AM, Ronald Bradford wrote: > > Presently the oslo.config Opt class has the attributes > > deprecated_for_removal and deprecated_reason [1] > > > > I would like to propose that we use deprecated_reason (at a minimum) to > > detail in what release an option was deprecated in, and what release it > > is then removed in. > > You mean what release it *will* be removed in, right? Clearly, once it's > removed, there won't be any indication it ever existed ;) > > > I see examples of deprecated_for_removal=True but no information on why > > or when. i.e. Ideally I'd like to move to an implied situation of > > if deprecated_for_removal=True then deprecated_reason is mandatory. > > +1 +1 > > > A great example is an already documented help message in oslo.log > > configuration option use_syslog_rfc_format that at least provides a > > guideline. [2] shows a proposed review to take this low road approach. > > An image of what the change actually looks like in documentation using > > this approach [3]. This also needs #267151 that fixes an issue where > > deprecated options are not producing a warning message in docs. > > > > The high road would be to have a discussion about if there is a better > > way to mark and manage deprecated options. For example, if there was a > > deprecated_release and a removal_release attribute then a level of > > tooling could make this easier. I would be wary in considering this, as > > it adds complexity (is it needed), and just how many options are > > deprecated. I'd appreciate thoughts and feedback. > > Any improvement in this regard I think would enhance the user experience > considerably, thank you Ronald for tackling this area. I'd also suggest > cc'ing (or sending a separate ML post) to the openstack-operators@ ML to > gather feedback from ops folks. Good idea. Maybe we could generate a warning when deprecated_for_removal is True instead of a string? Then when the value is a string we could use it as part of the deprecation warning when the option is being set in a deployment. Doug > > Best, > -jay > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Oslo] Improving deprecated options identification and documentation
On 01/14/2016 11:45 AM, Ronald Bradford wrote: Presently the oslo.config Opt class has the attributes deprecated_for_removal and deprecated_reason [1] I would like to propose that we use deprecated_reason (at a minimum) to detail in what release an option was deprecated in, and what release it is then removed in. You mean what release it *will* be removed in, right? Clearly, once it's removed, there won't be any indication it ever existed ;) I see examples of deprecated_for_removal=True but no information on why or when. i.e. Ideally I'd like to move to an implied situation of if deprecated_for_removal=True then deprecated_reason is mandatory. +1 A great example is an already documented help message in oslo.log configuration option use_syslog_rfc_format that at least provides a guideline. [2] shows a proposed review to take this low road approach. An image of what the change actually looks like in documentation using this approach [3]. This also needs #267151 that fixes an issue where deprecated options are not producing a warning message in docs. The high road would be to have a discussion about if there is a better way to mark and manage deprecated options. For example, if there was a deprecated_release and a removal_release attribute then a level of tooling could make this easier. I would be wary in considering this, as it adds complexity (is it needed), and just how many options are deprecated. I'd appreciate thoughts and feedback. Any improvement in this regard I think would enhance the user experience considerably, thank you Ronald for tackling this area. I'd also suggest cc'ing (or sending a separate ML post) to the openstack-operators@ ML to gather feedback from ops folks. Best, -jay __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [Oslo] Improving deprecated options identification and documentation
Presently the oslo.config Opt class has the attributes deprecated_for_removal and deprecated_reason [1] I would like to propose that we use deprecated_reason (at a minimum) to detail in what release an option was deprecated in, and what release it is then removed in. I see examples of deprecated_for_removal=True but no information on why or when. i.e. Ideally I'd like to move to an implied situation of if deprecated_for_removal=True then deprecated_reason is mandatory. A great example is an already documented help message in oslo.log configuration option use_syslog_rfc_format that at least provides a guideline. [2] shows a proposed review to take this low road approach. An image of what the change actually looks like in documentation using this approach [3]. This also needs #267151 that fixes an issue where deprecated options are not producing a warning message in docs. The high road would be to have a discussion about if there is a better way to mark and manage deprecated options. For example, if there was a deprecated_release and a removal_release attribute then a level of tooling could make this easier. I would be wary in considering this, as it adds complexity (is it needed), and just how many options are deprecated. I'd appreciate thoughts and feedback. Regards Ronald [1] http://docs.openstack.org/developer/oslo.config/opts.html [2] https://review.openstack.org/#/c/267176/ [3] http://postimg.org/image/vdkh3x46t/full/ __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
