Open Stack

On 05/20/2016 04:26 AM, Markus Zoeller wrote:
> On 05/19/2016 09:18 PM, Ben Nemec wrote:
>> On 05/17/2016 07:27 PM, Matt Fischer wrote:
>>>
>>>      If config sample files are being used as a living document then that
>>>      would be a reason to leave the deprecated options in there. In my
>>>      experience as a cloud deployer I never once used them in that manner
>>>      so it didn't occur to me that people might, hence my question to the
>>>      list.
>>>
>>>      This may also indicate that people aren't checking release notes as
>>>      we hope they are. A release note is where I would expect to find
>>>      this information aggregated with all the other changes I should be
>>>      aware of. That seems easier to me than aggregating that data myself
>>>      by checking various sources.
>>>
>>>
>>>
>>> One way to think about this is that the config file has to be accurate
>>> or the code won't work, but release notes can miss things with no
>>> consequences other than perhaps an annoyed operator. So they are sources
>>> of truth about the state options on of a release or branch.
>>
>> On this note, I had another thought about an alternative way to handle
>> this.  What if we generated one sample file without deprecated opts, and
>> another with them (either exclusively, or in addition to all the other
>> opts)?  That way there's a deprecation-free version for new deployers
>> and one for people who want to see all the current deprecations.
>>
> 
> I'm not sure if it is well known that the "configuration reference" 
> manual provides a summary page of new, updated and deprecated config 
> options at [1].

Ah, I thought I had heard something about that but I couldn't find it.
I wonder if we could link it from
http://docs.openstack.org/developer/nova/sample_config.html

> Also, the release notes have already a section to announce the 
> deprecation of a config option and this should be the source of truth 
> IMO. From Nova I can tell that it is part of the normal reviews to 
> ensure that a reno file (with a good explanation) is part of the change 
> when deprecating something (see a updated-per-commit version at [2]). 
> Introducing yet another way of telling people what's deprecated would 
> weaken the position of the release notes which I'd like to avoid.

The problem is that the ultimate source of truth is the code, and since
the sample config is generated from the code it's the only method not
subject to human error.  As I said earlier in the thread, I personally
agree that this is release note information and would prefer to rely on
the logged deprecation warning to address the human error case, but at
the same time I can understand that some people are not okay with that
so I'm trying to find an alternative that both cleans up the sample
config and still leaves the deprecations somewhere for people to find.

> 
> References:
> [1] 
> http://docs.openstack.org/mitaka/config-reference/tables/conf-changes/nova.html
> [2] 
> http://docs.openstack.org/releasenotes/nova/unreleased.html#deprecation-notes
> 
>>>
>>>
>>>
>>>      Anyways, I have no strong cause for removing the deprecated options.
>>>      I just wondered if it was a low hanging fruit and thought I would ask.
>>>
>>>
>>> It's always good to have these kind of conversations, thanks for
>>> starting it.
>>>
>>>
>>>
>>> __________________________________________________________________________
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe: OpenStack-dev-request at 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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>