What's missing from our changelogs [LWN.net]

What's missing from our changelogs

Posted Jul 24, 2013 22:11 UTC (Wed) by lrothc (subscriber, #41210)
Parent article: What's missing from our changelogs

I think one of the most important things in the history of a patch would be the email thread where it was discussed in public mailing lists. They are usually very verbose and, especially in controversial cases, contain the details of the discussions that affected the final version.

I very often find myself googling for the commit summary string as a way to figure out what has really led to the patch in question.

Now, how that could be incorporated in the commit log beats me.

to post comments

What's missing from our changelogs

Posted Jul 24, 2013 22:43 UTC (Wed) by blackwood (guest, #44174) [Link]

In drm/i915 I simply demand that review needs to be reflected in the commit, no matter what. So either the patch gets updated or the commit message needs improvement since if it would have been perfect no questions would have popped up in review.

For similar reasons I also insist that the revision log of individual patches is kept as part of the commit message (and not hidden below the -- line). We also use a bit more elaborate commit message citation layout (essentially git show up to the patch headline) so that author, committer, sha1 and headline is all there at a glance.

It's a lot more work than onleliners but imo enforcing high standars for commit messages is really worth it when digging through history.

What's missing from our changelogs

Posted Jul 25, 2013 2:01 UTC (Thu) by nevets (subscriber, #11875) [Link] (14 responses)

The scripts I use extract the message id from the email from a patch that is sent to me and its automatically added to the change log. They look like this:

Link: http://lkml.kernel.org/r/20130718184712.GA4786@redhat.com

That maps to marc.info/?i=20130718184712.GA4786@redhat.com which is the email of the patch. Usually from that, you can get the thread, which *is* very useful. I just used it a few minutes ago to figure out why some function was called in the MIPS code.

What's missing from our changelogs

Posted Jul 25, 2013 8:02 UTC (Thu) by lacos (guest, #70616) [Link] (4 responses)

This. Message-IDs are very important, and it's good that some public archives support search by msgid. For example, the URL format for gmane is

http://news.gmane.org/find-root.php?message_id=2013071818...

A further improvement is storing the original subject (including the "bag of tags" part) of the patch email (if the patch was posted to and applied from a list) as a "pseudo header". This helps identifying a series using just the git commit log (due to the patch numbering being captured).

What I miss is some way to save cover letters as standalone, no-code-change commits.

What's missing from our changelogs

Posted Jul 25, 2013 8:32 UTC (Thu) by johill (subscriber, #25196) [Link] (1 responses)

There's an easier redirect one for gmane:

http://mid.gmane.org/20130718184712.GA4786@redhat.com

What's missing from our changelogs

Posted Jul 25, 2013 8:44 UTC (Thu) by lacos (guest, #70616) [Link]

Interesting! Thanks!

(Still I like to end up immediately in the threaded / frames interface.)

What's missing from our changelogs

Posted Jul 25, 2013 12:39 UTC (Thu) by hmh (subscriber, #3838) [Link] (1 responses)

You could have the entire patch series as a temporary (topic) branch, and the cover letter as the [empty] merge commit log message, and you can do that right now.

This works well only when the patch stack is going in through the same tree, obviously.

As for notes, their out-of-band nature will complicate a secure workflow somewhat, but it should be possible to do it.

What's missing from our changelogs

Posted Jul 26, 2013 0:53 UTC (Fri) by aliguori (guest, #30636) [Link]

Empty commits dont survive a rebase which makes it hard to use for topic branches.

What's missing from our changelogs

Posted Jul 25, 2013 9:29 UTC (Thu) by lrothc (subscriber, #41210) [Link]

Ah, this looks good. I've been using the "find message ID" kind of thing when referencing email discussions, but it never occurred to me to include it in the tags section of the commit log.

But I think it would be better if this became more standard. Maybe if git itself would save the message ID so it could be easily looked up.

What we're missing here is a way to make it possible to find email discussions by looking at *any* commit in the git log. If there is a commit for which the message ID cannot be found in any public mailing lists, that would be a red flag telling us that the commit was not reviewed publicly.

What's missing from our changelogs

Posted Jul 25, 2013 12:29 UTC (Thu) by aliguori (guest, #30636) [Link] (7 responses)

I do the same thing but I do it in the form of a Message-id: tag. That way you don't have to worry about links breaking over time.

Here's an example:

http://git.qemu.org/?p=qemu.git;a=commit;h=fd1d9926e91f42...

Besides being a good way to associate a commit with a mail thread, it is useful for generating automatic "Thank you" notes when a patch is applied.

What's missing from our changelogs

Posted Jul 25, 2013 13:02 UTC (Thu) by nevets (subscriber, #11875) [Link] (6 responses)

We use to use LKML-Reference: tags that just included the message-id, but Linus hated it:

https://lkml.org/lkml/2011/3/28/460

Which was changed to the link format of:

Link: http://lkml.kernel.org/r/<message-id>

That way we have a link to the message that you can easily find, and if you are worried about that link disappearing, you have the message-id in the link. The best of both worlds.

But you should know that Linus hates just having the message-id as a tag.

What's missing from our changelogs

Posted Jul 25, 2013 16:58 UTC (Thu) by aliguori (guest, #30636) [Link] (5 responses)

Fortunately Linus doesn't control QEMU development :-)

A message-id is infinitely more useful than a link. There is no programmatic way of getting a message-id from a link so you can't generate email responses without it.

People just need to learn how to use mid.gmane.org :-)

What's missing from our changelogs

Posted Jul 25, 2013 19:02 UTC (Thu) by marcH (subscriber, #57642) [Link] (3 responses)

Or even better: desktop systems could somehow add message IDs to the list of MIME types and handlers they support. Then you could just click on them and this would automatically open the thread in your mail indexer of choice.

What's missing from our changelogs

Posted Jul 27, 2013 18:41 UTC (Sat) by mathstuf (subscriber, #69389) [Link] (2 responses)

Is there a way to tell a Message-Id from an email address? How would you determine that some string is an ID without something like message-id: (like email:)?

What's missing from our changelogs

Posted Jul 27, 2013 22:59 UTC (Sat) by marcH (subscriber, #57642) [Link] (1 responses)

Yes I was assuming something like Message-ID://

What's missing from our changelogs

Posted Aug 3, 2013 22:54 UTC (Sat) by mp (subscriber, #5615) [Link]

I guess you mean mid:.

What's missing from our changelogs

Posted Jul 26, 2013 3:02 UTC (Fri) by nevets (subscriber, #11875) [Link]

I don't see the problem with the way we do the links. The link includes the message id. You get the best of both worlds.