Re: [libvirt] [PATCH] news: Make changes understandable for users
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.
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 :)
--
Andrea Bolognani / Red Hat / Virtualization