[libvirt] [PATCH] news: Make changes understandable for users
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. Signed-off-by: Martin Kletzander <mkletzan@redhat.com> --- docs/news.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/news.xml b/docs/news.xml index eb0f2426be25..494c6489b9c5 100644 --- a/docs/news.xml +++ b/docs/news.xml @@ -706,7 +706,7 @@ </change> <change> <summary> - logical: Need to overwrite/clear more than just first 512 bytes + Overwrite (clear) 2 KB instead of just 512 bytes when initializing logical device </summary> </change> <change> -- 2.12.2
On Mon, Mar 27, 2017 at 22:25:39 +0200, Martin Kletzander 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 :-)
Signed-off-by: Martin Kletzander <mkletzan@redhat.com> --- docs/news.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/news.xml b/docs/news.xml index eb0f2426be25..494c6489b9c5 100644 --- a/docs/news.xml +++ b/docs/news.xml @@ -706,7 +706,7 @@ </change> <change> <summary> - logical: Need to overwrite/clear more than just first 512 bytes + Overwrite (clear) 2 KB instead of just 512 bytes when initializing logical device </summary> </change> <change>
ACK Jirka
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, 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
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
On 03/29/2017 03:54 AM, Andrea Bolognani wrote:
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.
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. 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> (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.
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.
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. 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. John
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@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 03/30/2017 11:26 AM, Andrea Bolognani wrote:
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.
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".
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.
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-/... John
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 :) -- Andrea Bolognani / Red Hat / Virtualization
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
participants (4)
-
Andrea Bolognani -
Jiri Denemark -
John Ferlan -
Martin Kletzander