WineConf action items

[Jeremy White]

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_Explanation_of_the_Patch

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_messages.