[openstack-dev] [openstack-manuals] What the status of DocImpact

Doug Hellmann doug at doughellmann.com
Mon Apr 25 12:57:13 UTC 2016


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



More information about the OpenStack-dev mailing list