[libvirt-users] How about giving commit ID in release notes

[Andrea Bolognani]

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