[libvirt] [PATCH] news: Make changes understandable for users

[Andrea Bolognani]

On Mon, 2017-03-27 at 22:38 +0200, Jiri Denemark wrote:
> > When reading release notes, patch summary is not always the best
> > description of what users can expect in new version.  I propose
> > changing it slightly so that it describes what exactly happens and
> > when.
> > 
> > However, we do not have to add every single code change to the news
> > file, that would be ridiculous and unreadable for users.  If the patch
> > subject needs changes like this one, I'm rather tempted to say that
> > such changes should not be in the news file at all.  So that would be
> > the other way how to fix this.
> 
> I agree, I think we should change the "Bug fixes" part to list only
> important/critical bug fixes. It's not going to be perfect since a bug
> importance is a subjective thing, but we could at least make developers
> think about it :-)

It's already supposed to work that way. And yes, it's always
going to be subjective and imperfect :)

I guess the criteria for documenting a bug fix in the release
notes would include the impact the bug had, both in the sense
of how many people are likely to be affected, and how easy it
was to run into it; more criteria could be the amount of time
the bug has been present (bugs that have remained unfixed for
years are unlikely to be release notes material), whether or
not it was possible to work around it and just how basic the
feature broken because of it is.

This one looks like it would qualify on several accounts,
but it could also definitely use a description to flesh out
exactly what was changed, something along the lines of

  <summary>
    Initialize volumes properly when building LVM storage pools
  </summary>
  <description>
    Volumes containing filesystem signatures need to have it
    wiped out before they can be used in an LVM storage pools.
    libvirt was unable to wipe out the signature for some
    filesystem (such as ext4) but that limitation has now been
    addressed.
  </description>

-- 
Andrea Bolognani / Red Hat / Virtualization