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

[Martin Kletzander]

On Tue, Mar 28, 2017 at 08:09:02PM +0200, Andrea Bolognani wrote:
>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>
>

Yeah, that's almost perfect (s/an LVM/LVM/), but I understand that not
everyone wants to come up with such description.  It would not have to
be if it was similarly worded in the commit message.

Anyway, I guess I'm just overreacting to some of these changes.  I'm
sorry for that.  I just feel like we went out of our ways to make
something nicer for the users out there, and start falling back into the
old tracks not long after it.  I compare it to git's release notes [1]
which I always find a) very understandable and b) to the point
(i.e. brief, no fuzzing around, but also missing only information you
can easily find out yourself, e.g. in a man page), but I don't know why
I'm so touchy regarding this subject.

Martin

[1] https://github.com/git/git/blob/master/Documentation/RelNotes/2.12.2.txt

>-- 
>Andrea Bolognani / Red Hat / Virtualization
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20170328/dcebffc2/attachment-0001.sig>