Open Stack

On Fri, Feb 26, 2016 at 1:07 PM, Monty Taylor <mordred at inaugust.com> wrote:
> 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.
>

++

Agreed! Just know who your audience is :D

Flavio

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



-- 
@flaper87
Flavio Percoco