On 11/02/2017 10:24 AM, Alexandre Julliard wrote:
- We'll start to use more detailed git commit messages, including bug references. Jeremy volunteered to research best practices from other projects so we can come up with some standards for what the messages should look like.
As far as I can tell, there is broad consensus on this. Of the 8 or 10 projects I sampled, if I could find a detailed description of how commit messages should be structured, they were more or less all the same.
The keys are: Subject line < 78 characters (~ 50 best), no period, imperative Prefix subject with subsystem, e.g. 'ntdll: usleep everywhere'. Patch prefixes are quite common (e.g. [PATCH], [RFC], [n/m]), but I'm going to treat that out of scope for this research. The body of the commit message should contain a why and a how but not a what. URLs are to be avoided; better to summarize what would be linked. The kernel puts this nicely by saying that the ideal is that a commit log require no external resources to understand. Surprisingly, none of the guidelines I read emphasized brevity. That startled me. Bug # references are good to include, but sadly, this was the one area where I didn't find any real consensus.
The kernel wants a URL to bugs. glibc uses [BZ #nnnn]. Github projects use just #nnnnn. OpenStack uses 'Closes-Bug: nnnnn' and (and Partial-Bug and Related-Bug). Other projects use 'Bug: nnnnn', and one uses 'bug #nnnnn'. I'd be tempted to argue for 'Bug nnnnn', with any automated scripts we write also accepting 'bug:nnnnn' (etc).
I saw one project (and now I can't recall which one :-/), that requested related bug numbers be provided on a separate, final line. That struck me as overkill, although I can recall seeing the git log and thinking it looked pretty :-/.
Cheers,
Jeremy
p.s. Here are 5 of the pages I reviewed:
Git: https://github.com/git/git/blob/master/Documentation/SubmittingPatches Xorg: https://www.x.org/wiki/Development/Documentation/SubmittingPatches/ Kernel: https://www.kernel.org/doc/html/v4.12/process/submitting-patches.html glibc: http://sourceware.org/glibc/wiki/Contribution%20checklist#Detailed_Explanati...
A general discussion by an OpenStack Nova author who claimed to also do a survey like this: https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_mess....