Commit Messages

Was sind gute Commit Messages?

Commit Messages sollen anderen Beteiligten an einem Projekt mitteilen was Du in Deinem Commit getan hast. Damit diese Info effizient und auch elektronisch verwertbar sind (z.B. zur Aufbereitung eines whats_changend.txt) gibt es ein paar Regeln die beachtet werden sollten.

Gute Commit Messages ersparen anderen Beteiligten eine aufwendige Suche und steigern die Effektivität. Gute Commit Messages sind ebenfalls der Baustein für ein treffsicheres Suchen zu späterer Zeit.

Aufbau einer Commit Messages

Die erste Zeile eines Commits besteht immer aus einer kurzen Zusammenfassung Deines Commits. Diese sollte nicht mehr wie 50 Zeichen umfassen. Es ist gute Praxis die Funktion, die logische Einheit oder auch eine Bugnummer gefolgt von einem Doppelpunkt der kurzen Zusammenfassung voranzustellen.
Hast Du nun noch mehr mitzuteilen, das wird fast immer der Fall sein, dann beachte folgendes. Die zweite Zeile bleibt prinzipiell leer! Ab der dritten Zeile beginnt Deine ausführlichere Darstellung Deines Commits. Aber auch hier sollte man sich daran halten das alle Zeilen nicht länger wie 72 Zeichen sein sollen. Für die Strukturierung Deiner Punkte kannst Du z.B. diverse Anführungspunkte benutzen wie z.B. *, -, #. Schreibe Deine Nachricht in der gegenwartsbezogenen Verlaufsform!

Ein Beispiel aus der Linuxkernelentwicklung. http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=ac04fee0b5c55bbac0858727a4154110b55d3f5a

loop: export module parameters

Export 'max_loop' and 'max_part' parameters to sysfs so user can know
that how many devices are allowed and how many partitions are supported.

If 'max_loop' is 0, there is no restriction on the number of loop devices.
User can create/use the devices as many as minor numbers available. If
'max_part' is 0, it means simply the device doesn't support partitioning.

Also note that 'max_part' can be adjusted to power of 2 minus 1 form if
needed. User should check this value after the module loading if he/she
want to use that number correctly (i.e. fdisk, mknod, etc.).

Tips für Gute Commits

Ein Commit sollte nie die Buildfähigkeit brechen!

Als eine goldene Regel für das Commiten gilt das ein Commit niemals die Funktionalität des Projektes beeinträchtigen sollte. Dies bedeutet das jeder andere der am Projekt mit arbeitet im Stande sein sollte das Projekt auch mit Deinem Commit noch Bauen können muss. Prüfe Deine Arbeit bevor Du etwas commiten willst!

Du bist nichts besonderes!

Jeder denkt das er gute Messages schreibt. In den meisten Fällen ist dies auch so. Aber jeder, auch Du, wird nachlässig nach einer gewissen Zeit! Wenn Du denkst das Du außergewöhnliche Commits schreibst dann schau kritisch über die letzten 100 Commits, wie viele von denen würdest Du wirklich "außergewöhnlich" bezeichnen? Nur aus Spaß, probiere es einmal.

Mache einfache Commits!

Dies kann man fast wörtlich nehmen, auch komplexen Sachen lassen sich in der Regel in Einzelcommits erledigen. Ein Commit soll nach Möglichkeit ein Problem lösen bzw. eine Neuigkeit einbinden etc. Ein Commit sollte eine logische Einheit bilden. Es kann sich später heraus stellen das genau dieser Commit revertet werden muss, dann soll dies auch mit dem reverten dieses einzelnen Commits möglich sein und nicht durch verschiedenste Commits verteilt sein! Dies hilft auch beim Erstellen der Commit Messages.
Beachte dies wenn Du eine Commit Message erstellst! Es gibt auch das Gegenteil, eine zu lange Nachricht. Sollte Deine Commit Nachricht lang sein frage Dich ob Du Deinen Commit nicht weiter aufsplittest.

Sei spezifisch und genau! Hilf es einfach zu finden!

Folgende Message hat sicherlich jeder schon gesehen oder gar selber verfasst, die schlechteste aller möglichen Messages!

fixed some bugs

Wow, wer hätte das gedacht! Aber es gibt eigentlich niemanden der absichtlich Bugs einbaut! Natürlich wird Dein Commit dazu da sein um vorhandene Fehler zu beseitigen.
Wenn Du eine größere Menge an Fehlern gefunden und beseitigt hast dann schreibe dies auch bitte! Erkläre was Du wo warum gemacht hast. Auch Du könntest mal später nach etwas suchen was du nur noch inhaltlich weist, und genau dann ist eine Suche in den Commit Messages Dein Vorteil. Besser wäre eine Commit Message wie:

Fixed bad allocations in image processing routines

Erkläre nicht Deinen Code, erkläre warum Du es genau so implementiert hast!

Deinen Code kann jeder sehen und lesen, deshalb ist es unnütz zu erklären was Du programmiert hast. Wenn Du überzeugst bist von Deinem Code, und das bist Du doch sicher, erkläre warum Du die Funktionalität genau so aufgebaut hast.

Kommuniziere Auffälligkeiten und Besonderheiten!

Du hast etwas schönes Neues für Dein Projekt, aber da es noch so neu ist und Du nicht alle Varianten prüfen konntest oder wolltest dann teile dies mit!

Adding a special GUI Option for the new entry XY

Dies beschreibt zwar Deine Arbeit, dies aber auch nur halb. Besser ist es zu mindestens noch mitzuteilen was funktioniert und wo es noch Probleme geben könnte.

Tested a seperate GUI entry, it works for the common way,
but the function() for coloring may not working for the old models

Stelle keine anderen Mitglieder bloß!

Du hast Code gefunden der nur so vor Fehlern strotzte? Korrigiere ihn einfach. Du warst auch mal Anfänger!

Fixed up heavy wrong typo, created by Beginner

Diese Mitteilung ist nicht besonders hilfreich. Hilfestellungen und Diskussionen sollten in einer Mailingliste oder Forum stattfinden. Folgendes wäre besser.

Fixed wrong typo in function() that come with Revision XYZ

Quellen

• wildbit.com
• tbaggery.com
• lbrandy.com
• who-t.blogspot.com