Re: Git Commit Messages

[Shaun McCance <shaunm gnome org>]

On Tue, 2010-06-01 at 19:36 +0800, Paul Cutler wrote:
> On Mon, 2010-05-31 at 21:30 -0500, Shaun McCance wrote:
> > Hey folks,
> > 
> > I'd like to request that people start prefixing their commit
> > messages with [help]. Optionally, you can do the full path to
> > a file if you've edited just one file, but the [help] part is
> > the most useful.
> > 
> > Maintainers often look through logs, especially for creating
> > NEWS entries at release time. They have to wade through a lot
> > of stuff from developers, translators, and writers. It sucks
> > up cognitive load to mentally process a bare commit message
> > like "Minor edits". Instead, use "[help] Minor edits".
> > 
> > Thanks for your understanding.
> > 
> 
> Is this just for gnome-user-docs or any help files in any module?

All of them. Most developers use something like this already
to mark components or files that commits affect. They'll be
much happier with us if we do the same.

And, actually, for gnome-user-docs, it would be nice to use
something different. Use prefixes like [gnome2-user-guide]
to mark which document you worked on in a commit.

And for other multi-document modules, it helps to be more
specific. So, for example, you might use [gnotravex/help]
when working on the Gnotravex Help.

Basically, developers look at git logs, and they want to
know at a glance what a commit was for. Imagine looking at
all the commits in a module and coming across one with the
message "Fixed some spelling mistakes". You have no idea if
that was in the docs or the UI or the Klingon translation.
Those little prefixes help immensely.


-- 
Shaun McCance
http://syllogist.net/