[Scummvm-devel] ATTN: New commit log message conventions
Eugene Sandulenko
sev at scummvm.org
Sun Jul 18 15:58:09 CEST 2010
Hi all,
As we discussed in the past, we will be switching to git repository.
When exactly will that happen I am not yet sure, since my proposed
structure is not ideal, and I'm still working on it.
But in any case, it is good to start switching to it, and particularly,
start use more proper commit log messages. The rationale besides the
rules which will be described below is not just git, but that our
commit log will look more readable. With our 70+ active developer it is
sometimes difficult to grasp what exactly was changed by just looking
in the log.
Thus the rules are following (they're standard to git except
SUBSYSTEM thing):
=== [commit log message start] =====
SUBSYSTEM: Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Write your commit message in the present tense: "Fix bug" and not "Fixed
bug." This convention matches up with commit messages generated by
commands like git merge and git revert.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here
- Use a hanging indent
=== [commit log message end] =====
Particularly the critical is the first line. You may noticed that
several developers already started to use this scheme, particularly
take a look at Max's commit or mine. This first line is used in short
log format, and providing engine name, sound subsystem, backend name or
whatever lets decide quickly should reviewers look deeply into commit
or skip.
The subsystem names which were used so far:
- AGOS, SCI, SCUMM, whatever engine name
- SDL, Android, WII, NDS, whatever backend name
- OSystem: our middleware code
- i18n: internationalization
- GUI: all gui-related
- TOOLS: ScummVM tools module or built-in tools
- MIDI: MIDI sound-related
After first line there has to be an empty line which is used as
separator, and also this first line has to be short, less than 50
characters, so log will fit on standard 80 columns terminal.
Please, stick to this format, as it will help us grow in the future
with staying maintainable.
More to read:
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
http://kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages
Eugene
PS. Please copy this to Wiki.
More information about the Scummvm-devel
mailing list