Open Stack

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.

Internal details, library API changes, etc. -- any changes the
deployer is not going to see -- are better covered in the developer
documentation published under docs.openstack.org/developer.  It's
relatively easy to include the pbr-generated ChangeLog directly in
the documentation (check the source for any of the Oslo libraries
to see how we do that). Internal API changes can also be documented
in the docstrings using the `versionadded` directive. Mixing these
sorts of details into the deployer/operator notes makes those less
usable, because the reader will have to sort through a large number
of notes they don't care about in order to find the ones they do
care about.

Doug