Excerpts from Matt Riedemann's message of 2016-04-24 15:54:03 -0500: > 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 <d...@doughellmann.com > > <mailto:d...@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 > > > > > > 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. >
Great explanation, Matt! There are also far far more contributors making changes that need to be documented than we have on the documentation team, so we can't reasonably expect them to keep up. Decentralizing the documentation effort by doing the work in each project as changes are made ensures that we have good release notes at each milestone and release, without overburdening any one person or group with that work. That said, release notes don't have to be exhaustive documentation for a new feature or change. They should describe the change briefly, mention configuration options that are added or removed, and refer to more extensive documentation for more detail. Doug __________________________________________________________________________ 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
