On Tue, Mar 28, 2017 at 08:09:02PM +0200, Andrea Bolognani wrote:
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>
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. 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. Martin [1] https://github.com/git/git/blob/master/Documentation/RelNotes/2.12.2.txt
-- Andrea Bolognani / Red Hat / Virtualization
Attachment:
signature.asc
Description: Digital signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
