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

John Ferlan jferlan at redhat.com
Thu Mar 30 17:05:31 UTC 2017



On 03/30/2017 11:26 AM, Andrea Bolognani wrote:
> On Wed, 2017-03-29 at 06:34 -0400, John Ferlan wrote:
>> 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.
> 
> I guess it's very much a case-by-case situation. For
> example, we have one entry in the release notes that
> consists of just:
> 
>   Fix compilation on macOS
> 
> and that's okay, because there's nothing else to it:
> compilation on macOS was broken, and now it no longer is.
> 

When I look at that "alone" I wonder was it broken in the release before
or just within that release? There is a difference. How would one know
just from reading that tidbit.

If in in the release before then I would expect a description that would
indicate as of libvirt 2.3.0, macOS builds were broken due to some
nefarious reason. The problem is now resolved. If the builds were broken
after 2.4.0, but before 2.5.0 - should it really be mentioned? For that
one, I say no because it's just development "cruft".

> If I happen to be curious about how exactly it was broken,
> and how exactly it was fixed, I can peruse the git history
> and find out, but in all other cases I will be able to
> understand perfectly fine how the change affects, or fails
> to affect, me from that single sentence.
> 
> In the 512 bytes vs 2 KiB case, a user reading the release
> notes and not having run into the issue himself will
> probably be unable to figure out whether the fix affects
> him or not without digging further; moreover, even users
> who *have* been affected by the bug might be unable to
> immediately connect the failure they experienced at the
> time with the fix description. In either case, the release
> notes would have failed to achieve their purpose.
> 
>> 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>
> 
> I don't think that would be good enough, for the reasons
> explained above.
> 
> Notice how neither storage pools nor filesystems are
> entioned at all, for example: those are two keywords that
> I would definitely expect to be there.
> 

Well anyone who "follows" libvirt enough knows that 'logical:' is a
storage pool type, but as I've already pointed out - I agree the
information was a bit too lean, but I guess I was just looking at the
examples nearby and decided to just keep it short.

Of course what I'm still puzzled about is why my editor (vim) went to
the bottom of the file even though I had recently been adjusting things
at the top. Usually I end up on the same line. Wonder if I hit the magic
G by mistake.  I guess that's what I get for being in a hurry, being at
the end of a release, being lazy, or any other litany of excuses that
force one through the shaming process once their mistake is revealed for
all to see 8-/...

John


> At the end of the day, some changes can be fully described
> in a single sentence, but most can't.
> 
>> (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.
> 
> Yeah, that's the way I thought about doing it a while ago,
> and it still seems like a good idea to me. We should just
> have a URL in <reference>, so it would work for the Red Hat
> Bugzilla as well as whatever other Web thingy.
> 
>>> 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.
> 
> Definitely. The target for libvirt release notes is very
> much *not* libvirt developers, but rather downstream
> maintainers and users, both those who use libvirt directly
> and those who build their own software on top of it.
> 
> That's why we need to provide a high-level and as
> comprehensive as possible overview of changes between
> releases, providing enough context that digging through
> the git log is not required in the vast majority of cases
> while at the same time making sure we're not bogging it
> down with trivial or internal only details.
> 
>> 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.
> 
> Yup, it's a difficult balance to strike. We're certainly
> doing a much better job these days, but that doesn't mean
> we can't improve even further :)
> 
> -- 
> Andrea Bolognani / Red Hat / Virtualization
> 




More information about the libvir-list mailing list