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.mcgin...@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 <d...@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.
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.
Monty
__________________________________________________________________________
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
