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) __________________________________________________________________________ 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
