Open Stack

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.

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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
@flaper87
Flavio Percoco
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160226/58b66095/attachment.html>