2017-11-06 17:30 GMT+01:00 Jeremy White jwhite@codeweavers.com:
Subject line < 78 characters (~ 50 best), no period, imperative
As long as we're changing things, let's stop putting periods on the ends of our patch subject lines. Wine is one of very few projects that use trailing periods and it's caused me to accidentally format subject lines incorrectly when writing patches for other open source projects.
For simplicity, I'd like the line length recommendation to be the same for the first line and all subsequent lines. When I rewrote https://wiki.winehq.org/Submitting_Patches#The_commit_message two years ago, I put 72 characters as the recommended limit everywhere. I chose 72 characters based on the recommendation at http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html. In practice, Alexandre really doesn't care how long the first line is, and probably doesn't care about the subsequent lines either.
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.
Since we're going to merge wine-patches and wine-devel, we're definitely going to want [PATCH] in the subject. Furthermore, the test bot depends on the n/m syntax to know whether a patch needs to be tested with a previous patch applied.
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 :-/.
"Bug: 123456" is nice because it follows the same header syntax we use for Signed-off-by, and the bug tag could go its own line before the Signed-off-by tags. I don't have a strong opinion, but I like that syntax better than any of the others you mentioned.
Thanks for doing the best practices research!
-Alex