On Mon, 2017-03-27 at 22:38 +0200, Jiri Denemark wrote: > > When reading release notes, patch summary is not always the best > > description of what users can expect in new version.  I propose > > changing it slightly so that it describes what exactly happens and > > when. > >  > > However, we do not have to add every single code change to the news > > file, that would be ridiculous and unreadable for users.  If the patch > > subject needs changes like this one, I'm rather tempted to say that > > such changes should not be in the news file at all.  So that would be > > the other way how to fix this. >  > I agree, I think we should change the "Bug fixes" part to list only > important/critical bug fixes. It's not going to be perfect since a bug > importance is a subjective thing, but we could at least make developers > think about it :-) It's already supposed to work that way. And yes, it's always going to be subjective and imperfect :) I guess the criteria for documenting a bug fix in the release notes would include the impact the bug had, both in the sense of how many people are likely to be affected, and how easy it was to run into it; more criteria could be the amount of time the bug has been present (bugs that have remained unfixed for years are unlikely to be release notes material), whether or not it was possible to work around it and just how basic the feature broken because of it is. 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>

--  Andrea Bolognani / Red Hat / Virtualization

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.

> 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.

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(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list

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.

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.

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

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