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 :)