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

[John Ferlan]

On 03/29/2017 03:54 AM, Andrea Bolognani wrote:
> On Tue, 2017-03-28 at 22:17 +0200, Martin Kletzander wrote:
>>> 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.
> 
> I'll be honest: it took me several passes (and several
> minutes) to come up with that text, so I can see quite
> clearly how not everyone would be willing to spend the
> same amount of time and effort on release notes.
> 

I find it ironic that I went against my normal practice and tried not to
be verbose. Just copying the git commit id message for a one liner. And
now it's turning into a more lengthy description.

Another "thought" here would be that "bugs" would be required to list
their bz in the description section and the summary would be just the
"short" (e.g. < 72 chars) git commit message. Leaving the 'details' in
the bug for anyone that cared about "logical" storage pools to go read.
Thus, for this one would have:

<change>
  <summary>
    logical: Need to overwrite/clear more than just first 512 bytes
  </summary>
  <description>
    https://bugzilla.redhat.com/show_bug.cgi?id=1430679
  </description>
</change>

(oh and yes, I could have written a better commit id message, I did try,
but kept running too long).

Or instead of <description> it could be <reference>#</reference where
the underlying code builds the query using the bz #.  That way if
someone really wanted details they have a link to go to assuming of
course that bz # link was a redhat bz. I could well be some other bug
system, so just # may not work.

>> 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.
> 
> Git's release notes have clearly been written and edited
> by a single individual, so of course they're going to be
> more consistent in tone and style than whatever our fairly
> large community of contributors can come up with over the
> span of a release.

Release notes are kind of an "organic process" and should be tailored to
the needs of each product with the consumer of the release notes in
mind. Not everyone that uses libvirt keeps "up to date" with the daily
patches and knows (more or less) exactly what's going on.

What we're doing now is a lot better than having DV sorting the various
commit id messages into groups. I'm sure this has made release
generation a bit easier for him!

We need to find that "happy medium" of providing enough information
without overloading. I actually think we're doing pretty good at that
right now. We may have missed a few things along the way, but it's
become part of a review and check-in process relatively quickly. It's
not perfect and definitely won't please everyone's idea of aesthetics.

John

> 
> My original intention was to be more active on this front
> and provide more oversight, including editing entries
> outright if necessary. I have unfortunately failed to do
> a very good job so far, and I apologize for that.
> 
> But I wouldn't say all hope is lost: for starters, I'll
> try to find some time to improve the release notes for
> the current release before the end of the freeze. And
> since you seem to be taking interest in the issue, maybe
> we can both try to work on it on an ongoing basis? :)
> 
> -- 
> Andrea Bolognani / Red Hat / Virtualization
> 
> --
> libvir-list mailing list
> libvir-list at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list
>