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

[John Ferlan]

On 03/30/2017 01:52 PM, Andrea Bolognani wrote:
> On Thu, 2017-03-30 at 13:05 -0400, John Ferlan wrote:
>>> 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".
> 
> Of course it is the former: the release notes, as the name
> implies, document changes *between releases*.
> 
> The fact that eg. master might be broken at some point in
> time is merely an artifact of our development process and
> should not leak into the release notes. Same goes for the
> fact that we compile them throughout the development cycle
> rather than dropping them in a single piece right before
> tagging a release like git does.
> 
> [...]
>>> 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-/...
> 
> I hope you're being hyperbolic here, and don't really feel
> called out just because the discussion happened to spark
> from a commit tweaking one of your entries. That certainly
> wasn't the intention at all.
> 

Sorry not pointing any fickle finger of blame or fate over this at you
or anyone in particular beyond myself for all those excuses. Takes a bit
more to dig through my skin ;-)

> As I reckon we both agreed earlier, the process is still far
> from being perfect and we're still figuring out what works
> and what doesn't: let's get there by having an open discussion
> where we weigh the pros and cons of different approaches and
> hopefully end up choosing the best one as a result, just like
> we do for our code :)
> 

Exactly... especially since I sit in a home office where it's much
harder to wear those pink bunny ears of shame!

John