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. 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. Flavio > > > > > -- Brant > > > > __________________________________________________________________________ > > 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 > > > __________________________________________________________________________ > 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
