On Fri, Feb 26, 2016 at 1:07 PM, Monty Taylor <mord...@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.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. >
++ Agreed! Just know who your audience is :D Flavio > 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 -- @flaper87 Flavio Percoco __________________________________________________________________________ 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
