[openstack-dev] [all] audience for release notes

Sean McGinnis sean.mcginnis at gmx.com
Fri Feb 26 15:17:50 UTC 2016


On Fri, Feb 26, 2016 at 09:03:49AM -0600, Brant Knudson wrote:
> On Fri, Feb 26, 2016 at 6:34 AM, Doug Hellmann <doug at doughellmann.com>
> wrote:
> 
> > I've had a few conversations recently about "appropriate" content for
> > release notes, so I thought it was worth starting a separate thread here
> > to clarify.
> >
> > We have 3 potential audiences for release notes:
> >
> > 1. Developers consuming libraries or other code directly.
> > 2. Deployers and operators.
> > 3. End-users.
> >
> > We implemented reno for this cycle to replace the old wiki-based
> > system for writing release notes for deployers, operators, and
> > end-users. We have in-tree developer documentation for Developers. The
> > two sets of documentation are meant for different purposes, so we need
> > to think about what information we publish in each.
> >
> > As you are writing release notes using reno to be published under
> > docs.openstack.org/releasenotes, please keep in mind the audience
> > is *not* someone who is necessarily going to be looking at code or
> > writing apps based on libraries we produce. Highlight information
> > that deployers and operators will need, like changes to configuration
> > options or service behaviors. Describe REST API changes that an
> > end-user may need to know about.
> >
> >
> python-keystoneclient doesn't provide config options, so there should never
> be release notes for it. Probably best to disable releasenote generation
> for most of the python-*client libraries.

I actually see value in having the release notes for the client
libraries. Not always, but occasionally functionality gets merged in the
service but not added to the client in time. Having release notes for
exposing new functionality can make it easier to scan through notes to
find the supported version you need.

I can see valid arguments on either side of the argument though.

> 
> -- Brant

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




More information about the OpenStack-dev mailing list