Open Stack

On 20.05.2016 16:51, Ben Nemec wrote:
> 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
> 

Sure, should be a simple patch to [1].

>> 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.

References:
[1]
https://github.com/openstack/nova/blob/master/doc/source/sample_config.rst

-- 
Regards, Markus Zoeller (markus_z)