On Tue, 03 Apr 2012 18:24:03 -0700, Tim Starling tstarling@wikimedia.org wrote:
On 04/04/12 10:31, Daniel Friesen wrote:
We have a policy of restricting the length of the first line. Since it's used by gerrit as email subjects. So as a result when I write the first line of a git commit I inevitably leave out critical information. So the first line of a commit misses out information that if I had a RELEASE-NOTES line to write would be in there.
Also, I've noticed that a decent portion of my commits are small backend stuff or modifications. Stuff which have little business being inside RELEASE-NOTES. Frankly if we do it that way RELEASE-NOTES becomes little more than a commit log, which is a lot less valuable than the RELEASE-NOTES we currently have.
I agree with this. Usually I target commit messages at developers and release notes messages at users. Sometimes that means that the two texts have nothing in common at all.
I think the release notes could go further down in the commit message, perhaps with a footer style similar to Gerrit's Change-Id, for example:
Refactored Foo.php, splitting animal classes from vegetable classes
- Used closures for EVERYTHING
- (bug 98765) Fixed a spelling error in a CSS class name
Release-Notes: (bug 98765) Renamed CSS class .foo-arbitary to .foo-arbitrary
-- Tim Starling
Another two related things I found:
Firstly: http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-chan... A git merge that seams to understand how to intelligently merge some types of changelog files. I thought this might be problematic to have everyone install. But thinking about it again. Gerrit is the one doing merges. If that can handle the RELEASE-NOTES format that we uses. Then theoretically installing it on the server gerrit uses and then configuring our release notes to use it could theoretically make Gerrit suddenly able to handle RELEASE-NOTES changes without conflicts.
And on release notes inside commit, another option: Using a 'release-notes' git notes namespace. http://progit.org/2010/08/25/notes.html
It has a disadvantage in the area of ease of use. (It'll be another thing that'll probably need another tweak to git-review) But it has the advantage that you can edit notes after commit without having to amend the code.