[asterisk-dev] Commit Message Guidelines updated

[Matthew Jordan]

Hey all -

Per a discussion had on this mailing list [1], I've gone ahead and updated
our commit message guidelines [2] to include that the affect subsystems
should be listed in the commit message summary when possible:

app_foo: Fix crash when widget is frobbed

(Or something along those lines)

Obviously, there may be cases where it is difficult to provide all affected
subsystems (documentation changes that span many modules, whitespace
cleanup, etc.) - so this is a suggestion, and not mandatory. Use common
sense when applying it.

In addition, as time has gone on, we as a project depend more and more on
good, well written commit messages. This is for two reasons:

(1) We have a lot of scripts for release summaries, announcements, JIRA,
Review Board, and other tools that look at the commit messages to know what
was fixed, what should be closed, etc. Proper commit message formatting is
essential for all of these tools to work in a painless fashion. When these
tools don't work, the burden is on the developer to 'clean up' after their
work - and that's not much fun.

(2) More importantly, as the Asterisk project continues and new developers
join, their only view into why a change was made is the commit history.
Often, developers who made the original change are no longer active in the
project or cannot remember why the change were made! Having proper commit
messages is essential to preventing regressions and the continued success
of the project.

As such, I've added a little bit of teeth to the commit message guidelines.
Repeated, flagrant abuses of the commit message guidelines can result in
suspension of your commit access. While we've never had to do this - and I
can't think of anyone today who does not write good commit messages - I do
think it is important to emphasize how critical good commit messages are to
the project. A developer who patches Asterisk with a bad commit message
does a disservice to their own work and to the project as a whole - and we
should, as a community of developers, not allow that.

Happy committing everyone!

[1] http://lists.digium.com/pipermail/asterisk-dev/2013-October/063203.html

[2] https://wiki.asterisk.org/wiki/display/AST/Commit+Messages

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20131031/5821f606/attachment.html>