Inspired from https://github.com/git/git/blob/master/Documentation/SubmittingPatches
The first line of the commit message should be a short description (50 characters is the soft limit), and should skip the full stop.
It is also conventional in most cases to prefix the first line with "area: " where the area is a filename or identifier for the general area of the code being modified, e.g.
LoginController: throw Exception if $userId is missingreadme.md: clarify the use of API
The body should provide a meaningful commit message, which:
-
explains the problem the change tries to solve, iow, what is wrong with the current code without the change.
-
justifies the way the change solves the problem, iow, why the result with the change is better.
-
alternate solutions considered but discarded, if any.
e.g. make xyzzy do frotz instead of
[This patch] makes xyzzy do frotz or Changed xyzzy to do frotz,
as if you are giving orders to the codebase to change its behaviour.
A perfect example would be something like:
AdminController: better handling of course/lesson deletion
- don't pretend a Course has Lessons when any Exception is thrown
- if an Exception happens, display it
- if a Course has Lessons, display the correct error message
- don't test against user role as Acl takes care of that alread
This greatly improves reviewing patches, as well as helping other developers to quickly find where changes happened to a certain area of the code, etc...