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

Monty Taylor mordred at inaugust.com
Fri Feb 26 17:07:29 UTC 2016


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.

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





More information about the OpenStack-dev mailing list