[openstack-dev] [all] Deprecated options in sample configs?
mzoeller at linux.vnet.ibm.com
Fri May 20 15:31:45 UTC 2016
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
>>>> 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 .
> Ah, I thought I had heard something about that but I couldn't find it.
> I wonder if we could link it from
Sure, should be a simple patch to .
>> 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 ).
>> 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.
>>>> 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.
Regards, Markus Zoeller (markus_z)
More information about the OpenStack-dev