Open Stack

Excerpts from Monty Taylor's message of 2016-02-26 11:07:29 -0600:
> On 02/26/2016 10:41 AM, Doug Hellmann wrote:
> > Excerpts from Flavio Percoco's message of 2016-02-26 11:43:09 -0400:
> >> On Fri, Feb 26, 2016 at 11:17 AM, Sean McGinnis <sean.mcginnis at gmx.com>
> >> wrote:
> >>
> >>> 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.
> >>>
> >>
> >> I could be wrong but I don't think the recommendation was to not have
> >> release notes for libraries. I think the intent is to not make part of the
> >> service release notes some internal API changes.
> >
> > That's right, although the same applies for the libraries.
> >
> > We used to document release notes from Oslo code in the service-specific
> > release notes, because although the options were defined in Oslo
> > code they were actually exposed through the services when the code
> > was copied in-tree from the incubator. We're no longer relying on
> > incubated code, so we we added reno to a couple of Oslo libraries
> > this cycle so we could have a place to document changes to configuration
> > options for deployers.
> >
> > Client libraries are a little trickier. There may well be changes
> > that a deployer would care about -- new environment variable handling,
> > changes in default behavior that might affect service performance,
> > etc.  Documenting those only in the developer docs isn't going to
> > expose them to the audience that needs to see them. These changes
> > come up less often than with some of the other projects, so it may
> > not be necessary to manage the release notes until there's actually
> > need to do publish something. On the other hand, if a change is blocked
> > until there's a way to publish release notes for it, that seems like a
> > bad outcome.
> >
> >> Ultimatedly, I think the general recommendation is "Know your audience".
> >> Avoiding getting to much into the technical details of a change is normally
> >> better. People interested in the internal details of a change will likely
> >> find that information elsewhere. For everyone else, there are release notes
> >> that should be informative enough and contain relevant information for
> >> their deployments, upgrades, security, etc.
> >
> > Yes, that.
> 
> On the note of 'known your audience' - I'd actually argue that we do 
> want release notes for libraries and that the audience for them is not 
> deployers at all, but developers consuming them. If there is a 
> library-related release note that affects a deployer, that release note 
> is more likely to be useful in the corresponding server project related 
> to the change that starts to make use of new library behavior.

As a part of the way cross-project teams deal with our continuing
expansion after Big Tent, we're trying to get centralized teams out of
the way of good communication. In this case, we're shifting from
producing a single large release notes document at the end of each
release to managing release notes as we go, for each project,
separately.

All of the notes will still be easily accessible from the release
page on releases.openstack.org (see
http://releases.openstack.org/liberty/index.html for examples of
this), so consumers of the information have a central place to start
reading.  The producers of the information can more easily prepare
the relevant data as they do their work in the normal way, which
means no more mad rush at the end to write up the notes for the
release candidate.

All of that is doing the same thing to prepare release notes, for
more projects, in a different way. The thing that's completely new
this time around is having deployer-facing release notes for
libraries. As I explained, we didn't used to do that because we
didn't always have libraries.  You point out one case where it would
make sense to put notes in the server document, when a library
behavior change is explicitly enabled in a server project. However,
we have other changes where no server change is needed (this time
around we're removing a deprecated option from oslo.log). In fact,
the goal is to allow configuration option changes for libraries
without *any* server change in *most* cases.

I considered, when we designed reno, having the server release note
build work something like the sample config generator, and pull in
notes from dependencies as well. I decided that would actually be
worse, not just because all of our distro packagers would yell at
me (hi, zigo!), but because it would mean the notes for a given
service would depend on when the document was built, and what library
happened to be available at the time. That means a new release of
a library, with a new note, might result in an important note going
unmentioned.

So, while it's slightly more complicated to ask release notes
consumers to read multiple pages, it's the only way to produce
accurate information for them based on the versions of the things
they have in hand.  Since we're including release notes directly
in the library, and publishing them to the same place all of the
other release notes go, and linking to them from releases.openstack.org
just like the services, they won't be hard to find.

> 
> On the other hand, for consumers of libraries (of which I am one) things 
> like "defaults to V2 instead of V1" is a very important piece of 
> information.

Yes, that is another good example of a thing that should go into a
reno release note for the library.

Doug