A standard for commit messages

[Sebastian Huber]

On 02/23/2012 08:37 AM, Ralf Corsepius wrote:
> On 02/22/2012 07:16 PM, Gedare Bloom wrote:
>> Hi,
>>
>> I want to reboot the conversation. Please do not bring up ChangeLog or
>> $id$ or anything else that is not germane to the topic of the commit
>> message.
> Once more, these topics are closely tied together, whether you like this or not.
>
>> Joel suggested that the commit message be something that starts with a
>> simple phrase that reads like a title/headline for the commit. After
>> that phrase should come additional details. The first words are what
>> gets propagated to the vc list subject line, so we should make those
>> words count.
>
> Let me ask: What is the issue you are trying to resolve?
>
> 1. git format-patch?
> 2. git shortlog?
> 3. The vc-commit list subjects?
> 4. Implement unique "shortlogs"?
>
> The former 2 are git internal details, which are not of actual real world
> importance.

What is the real world?

>
> 3. is just a matter of vc-commit list implementation (Change it, let it parse
> _ChangeLogs_ (!) etc. if you don't like what it currently does.

Why change something that works if you don't sabotage it?

>
> 4. would be ... well, absurd.

Yes, this absurd.  We have the hopefully unique SHA1.

>
> In a nutshell, what you are trying to do basically it to try tying together
> _ChangeLogs_ (!) and git internals. Something I consider to be an invalid
> reasoning.

I consider this efficient and effective usage of Git.

>
>> If there is a bugzilla report associated with the commit then the
>> message should start with "PR #### - "; in many cases the title of the
>> bug report or something similar would work fine to begin the commit
>> message after the PR number.
>
> This is inapplicable in many cases, because
> a) the size of short logs is limited to carry "reasonable contents", i.e. it
> will be tedious to provide "reasonable shortlogs"

Of coarse not everything fits into one line.

> b) patches often cover many files and several topics at once.

These patches should be rejected.  Ideally a patch contains a minimal change 
set.  The source tree should be in a well defined state before and after the 
commit, e.g. everything compiles and the test suite passes on selected simulators.

> c) there are changes, were it doesn't make sense to provide "extensive
> changelogs" - In the past, we often resorted to provide ChangeLog entries for
> these.

Yes.

> d) with git, we also will see git generating "cryptic" messages (e.g. upon merges)

These messages in the master repository are an error.  In fact they do not show 
up recently since we are now more familiar with the Git usage.

>
>> The author and date tags are automatically generated so it is
>> unnecessary to state your (or anyone else's) name or the commit date
>> in the commit message. If you are committing on behalf of someone else
>> you should use the --author to credit the change.
>
> This is a topic, we seem to fundamentally disagree. I would expect it will be
> unlikely will be able to find a common ground.
>
>> Other suggestions?
>
> - Equipe this vc-commit script with more intelligence to have it produce better
> readable mails (Compare for the former CVS-logs, they weren't actually better,
> either).

The current mails are quite well.  What do you miss?  They show important meta 
information like author, date, a link to details.  They show the summary, the 
commit message, the files changed with details, and the changes itself.

> - Revert to previous practices/revive the ChangeLogs.

I only can cite Pavel Pisa once again:

http://www.rtems.org/pipermail/rtems-devel/2012-January/000142.html

-- 
Sebastian Huber, embedded brains GmbH

Address : Obere Lagerstr. 30, D-82178 Puchheim, Germany
Phone   : +49 89 18 90 80 79-6
Fax     : +49 89 18 90 80 79-9
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.