On Mon, 2018-07-09 at 14:43 +0200, Michal Privoznik wrote:

On 07/09/2018 10:35 AM, Han Han wrote:

...

Hello developers, Your release notes from libvirt(https://libvirt.org/news.html) are really helpful to our users and QAs. How about giving commit ID of each item in release notes, so that our user can gather more info from release notes. For example,in v4.5.0 release note, add commit ID on each item: capabilities: Provide info about host IOMMU support Capabilities XML now provide information about host IOMMU support. (commit dc34e7)

Though we can seach them from git, it is more accurate doing by the authors.

I like this. But should we give it some form, e.g. new element in news.xml?

<change> <summary>Some feature</summary> <commit>f572d396fae9206628714fb2ce00f72e94f2258f</commit> <description>Some description</description> </change>

Or is that an overkill?

I think adding a new element for it would definitely be the way to go, since the whole point of using XML as the source format is storing structured information instead of free-form text. Recording the Bugzilla link was also suggested in the past, which I feel would be a great idea - just never got around to it :) That said, for git commits specifically there are at least two issues I can think of: * most of the time, features and bugfixes happen over the span of several commits; having a "starting point" could be nice, but you're still going to have to look around a bit; * most importantly, when release notes are updated as intended, ie. along with the changes they're documenting, you don't know the commit hash yet. So you'd have to take your branch, rebase it on top of master, merge it into master, amend the last commit to include the hash for the commit you feel can best represent the change in the release, and only then you can push... Assuming, of course, nobody pushed anything in the meantime! Because then you'd have to repeat the last step again, possibly multiple times if it's a very busy day. All things considered, it seems like including commit information in the release notes would be quite a bit of effort and have a lot of room for error, so I'm not too convinced we want to move in that direction after all. Note that, for features and bugs tracked on Bugzilla, it's fairly common practice to add a comment pointing to the commit(s) once the relevant code has been merged, which means including a link to Bugzilla as mentioned above would kind of partially address this too :) -- Andrea Bolognani / Red Hat / Virtualization