Open Stack

On 4/24/2016 8:03 AM, ZhiQiang Fan wrote:
> but Document Team has so beautiful tables, and so convenient tools
> <openstack-doc-tools>, it is a huge waste of resource if we manually
> write it to release note in each project.
>
> So I want to figure out what have happened to prevent Document Team
> continuing previous workflow.
>
> Thanks
>
> On Sun, Apr 24, 2016 at 8:54 PM, Doug Hellmann <doug at doughellmann.com
> <mailto:doug at doughellmann.com>> wrote:
>
>     Excerpts from ZhiQiang Fan's message of 2016-04-24 08:00:10 +0800:
>     > Hi Doc Team,
>     >
>     > I want to know the recent status of DocImpact tag, is it
>     deprecated for
>     > config option changes now? If it's true, then what the workflow
>     for config
>     > reference now, any hint or link?
>     >
>     > Previously, when a patch has impact to document, including config
>     option
>     > changes, I usually ask contributors to add a DocImpact, hence
>     there will be
>     > a bug track the document issue.
>     >
>     > Recently, a patch lands in Ceilometer which adds two new options, and
>     > Ceilometer receives the auto created document bug. However, when I
>     submit a
>     > patch to openstack-manuals to fix it, I was told by a core that
>     such change
>     > is not needed any more, I searched latest merged patch in
>     openstack-manuals
>     > and found what he said is true, but still don't know why and what
>     action I
>     > should follow in Ceilometer/Aodh projects
>     >
>     > Thank you very much!
>     >
>     > ZhiQiang Fan
>
>     I recommend at a minimum including a release note using reno in the
>     patch changing any configuration options (adding, deprecating, changing
>     defaults, etc.).
>
>     Doug
>
>     __________________________________________________________________________
>     OpenStack Development Mailing List (not for usage questions)
>     Unsubscribe:
>     OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>     <http://OpenStack-dev-request@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
>

The point of adding a release note for new config options is because 
they are generally added for a feature, so the release note advertises 
that feature and how to use it (with the config option).

The point in adding a release note when deprecating and removing config 
options is because of the upgrade impact (another tag that would go 
unnoticed). Deployers are using the release notes when doing upgrades, 
so they need to be aware of these things without having to diff the 
massive config options pages between releases and try to sort everything 
out.

-- 

Thanks,

Matt Riedemann