Vorlage:Commit messages

Was sind gute Commit Messages und warum man diese erstellen sollte.

Commit Messages sind kein lästiges Beiwerk sondern dienen der Kommunikation und Information. Sie sollen Beteiligten und Interessenten eines Projektes mitteilen, was Du in Deinem Commit getan hast und warum Du es getan hast. Damit diese Infos effizient und auch elektronisch verwertbar sind (z.B. zur Aufbereitung einer ChangeLog Datei) gibt es ein paar Regeln die beachtet werden sollten. Gute Commit Messages ersparen anderen Beteiligten eine aufwendige Suche und steigern die Effektivität. Aussagekräftige Commit Messages sind ebenfalls der Baustein für ein treffsicheres Suchen zu späterer Zeit. Dies ist zum Beispiel dann besonders wichtig wenn man eine Fehlersuche betreiben muss, und dies üblicher Weise basierend auf den Commit Nachrichten tätigt.

Der Zeitaufwand für das Schreiben einer aussagekräftigen Message beläuft sich für gewöhlich nur auf wenige Minuten. Aber gerade dadurch wird das spätere Suchen in der History oder im Sourcecode wesentlich effizienter und der Entwickler kann sich seiner eigentlichen Beschäftigung, dem Programmieren, widmen. Wenn Du bisher noch nicht so gearbeitet hast, lies bitte folgende Hinweise und frage Dich, ob es nicht besser wäre, so zu arbeiten oder es zu mindestens zu versuchen.

Aufbau einer Commit Message

• Die erste Zeile eines Commits besteht immer aus einer kurzen! Zusammenfassung Deines Commits bestehend aus Zahlen und Buchstaben, jedoch ohne Anführungspunkte oder ähnliches.
  • Die erste Zeile sollte nicht mehr wie 50 Zeichen umfassen. Die üblichen Editoren helfen mit einer farblichen Hervorhebung beim Verfassen der Commit Message.
  • Danksagungen für Zuarbeit oder ähnlich gehören ebenfalls nicht in die erste Zeile!
  • Commit IDs (egal ob Kurzform oder Langform) haben in der ersten Zeile ebenfalls nichts zu suchen, wenn dann bitte im erläuternden Teil der Commit Message auf einen anderen Commit verweisen, sofern dies nötig ist.
    • Das hat unter anderem den Hintergrund, dass Commit-ID's nur auf passende Commits mit der jeweilig passenden Historie des zugehörigen Branches lokal und remote zeigen. Das funktioniert nicht mehr bzw. nur bedingt bei Cherry-Picks, egal ob lokal oder von Fremdprojekten, und sobald man lokal auf verschiedene Branches rebased, werden diese IDs ungültig. Sprich immer dann, wenn sich die Historie ändert und die Commit-IDs dort involviert sind, werden sie sich ändern. Wenn man auf einen Commit verweisen möchte, sollte man immer nur den Reintext der ersten Zeile des Commits als Verweis nehmen, denn der bleibt in der Regel gleich, auch bei Cherry-Picks, sofern die dortigen Committer sich an gewisse Konventionen halten. Die Texte kann man immer über die Git Suchfunktionen finden.
• Es ist gute Praxis die Funktion, die logische Einheit oder auch eine Bugnummer gefolgt von einem Doppelpunkt der kurzen Zusammenfassung voran zustellen.
• 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. [1]

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.).

HINWEIS:

Im Vi bzw. VIM lässt sich die maximale Textbreite mit

set textwidth=72

schnell und einfach auf 72 Zeichen setzen! Ein Eintrag dieser Anweisung in die ~/.vimrc veranlasst Vi bzw. VIM bei jedem Start diese Textbreite zu benutzen. Siehe auch Beispiel einer .vimrc

Tipps für Gute Commits

Ein Commit sollte nie die Buildfähigkeit brechen!

Als eine goldene Regel für das Committen gilt, dass ein Commit niemals die Funktionalität des Projektes beeinträchtigen sollte. Dies bedeutet, dass 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 daraufhin bevor Du etwas committen willst!

Commits sollten einen gewissen Mindestgrad an Information bieten. Dies kann einen bestimmten Eindruck über die Qualität eines betreffenden Repos hinterlassen. Macht man dies schlampig, entschuldigt das nicht unbedingt, auf eine rein privates Projekt zu verweisen. Ein Repository ist nie rein privat, solange jemand die Historie öffentlich verfolgen kann und somit zwangsläufig Interesse daran erweckt werden kann. Insbesondere wenn man ein Repository bei namhaften Hostern unterhält, auf dem sich auch renommierte Softwareanbieter aus der aller Welt tummeln. Wer permanent lieber oberflächlich damit umgeht, sollte sich dann lieber überlegen, sein Repository nur privat zu betreiben.

Du bist nichts besonderes!

Jeder denkt, dass 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, dass Du aussergewöhnliche Commits schreibst dann schau kritisch über die letzten 100 Commits, wie viele von denen würdest Du wirklich "aussergewöhnlich" bezeichnen? Nur so aus Spass, probiere es einmal.

Mache einfache Commits!

Dies kann man fast wörtlich nehmen, auch komplexe 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 herausstellen 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 kommt besonders zum Tragen, wenn man mit git bisect automatisierte Fehlersuche betreibt. Und dies hilft auch beim Erstellen der Commit Messages.
Beachte dies, wenn Du eine Commit-Message erstellst! Es gibt auch das Gegenteil, einen zu großen Commit. Sollte das der Fall sein, frage Dich, ob Du Deinen Commit lieber weiter aufsplittest. Allerdings kann man es auch übertreiben, indem man sprichwörtlich für jede kleinste Änderung einen Commit macht. Das macht dann auch keinen Sinn.

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!

fix foo id

Na toll, und was war da damit jetzt? Muss ich jetzt den Code durchforsten?

fix

Der Klassiker!

Im Moment des Commits sind für den Autor der Message die Umstände, warum, wie, weshalb usw. sicher bekannt und diejenigen, die das Problem detailliert verfolgt haben, könnten auch Bescheid wissen, aber ein simpler Hinweis, was da falsch war, oder wo das Problem behandelt oder besprochen wurde, wäre ein gewisser Mindestaufwand, den man hier betreiben sollte. Naturgemäß hat niemand wirklich Lust drauf, erst den Code zu durchforsteten und auch der Autor schaut unter Umständen nach Jahren dumm aus der Wäsche, wenn er seine eigenen Commits nicht mehr nachvollziehen kann.

Grundsätzlich gibt es sicherlich niemanden, der absichtlich Bugs einbaut! Natürlich wird Dein Commit dazu da sein, vorhandene Fehler zu beseitigen!
Wenn Du eine größere Menge an Fehlern gefunden und beseitigt hast, dann schreibe dies auch bitte! Erkläre, warum Du das gemacht hast. Auch Du wirst später mal nach etwas suchen, worüber Du nur noch im Ansatz bescheid weist, und genau dann ist eine gelungene Suche in den Commit Messages ein Vorteil. Besser wäre eine Commitmessage im Satz welche das WARUM zumindest andeutet wie:

Fixed bad allocations in image processing routines

Wie schon erwähnt wird das Finden von Commits auch erheblich vereinfacht, wenn man gewisse thematische Markierungen benutzt, indem man den Commit entsprechend generisch einleitet. Dies könnte z.B. der Name eines Features, eines Moduls (Funktion), eines Branches, Make-Target, einer Implementierung o.ä. sein. Siehe auch obiges Beispiel aus der Linuxkernelentwicklung.

modulX: Fixed bad allocations in image processing routines

oder um es auf einen bestimmten Vorgang einzugrenzen:

clean up: removed unused variables. 

So wird man nach Jahren wieder erkennen, dass hier jemand am ModulXY etwas an der Speicherbehandlung gearbeitet und unnütze Variablen aufgeräumt hat und kann die Änderung relativ schnell einordnen. Je nach Komplexität der Änderung, sollte man auch in Betracht ziehen, ausführlicher zu werden.

Sehr nützlich kann es sein, wenn man z.B. lokal viel in Branches arbeitet und hier naturgemäß kleinere Commits macht, diese mit dem Branchnamen markiert.

Branch_cleanups modulX: removed unused variables in ...

So fällt es leichter, die Commits auch noch ohne großes darauf schauen, einem Branch zuzuordnen. Wenn der Branchname auch noch ein Thema darstellt, kann man sogar nach einem Merge in den Master-Branch Rückschlüsse auf die Herkunft ziehen, ohne die Historie genauer zu studieren.

Es wird so schnell klar, sich hierbei Gedanken um etwas Organisation zu machen. Das ist noch nicht mal viel Aufwand. Man ist zumindest sich selbst dankbar und froh darüber, ohne großen Aufwand, irgendwann mal einen Commit zu finden, der genau zu einem Problem oder Vorgang passt. Schaue Dir andere Commits an, vergleiche diese mit Deinen.

Erkläre, was Du gemacht hast, erkläre, warum Du es genau so implementiert hast!

Dass Du am Code etwas programmiert, oder was auch immer Du am Code gemacht hast, kann jeder sehen und lesen, deshalb ist es generell ok dies anzumerken, aber erkläre, warum Du die Funktionalität genau so angepasst oder implementiert hast.

Teile Auffälligkeiten und Besonderheiten mit!

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

Unterlasse unnötige Interjektion

Sorry, aber das geht garnicht!

Solche Messages sind völlig unbrauchbar und eher peinlich, oder was will uns diese Nachricht sagen? Und welchen Eindruck hinterlässt so eine Message in einem automatisch generiertem Changelog, wenn das ein interessierter User oder Kollege liest.

Messages, die im Eifer des Gefechts entstehen sind sicher kein Problem, solange aus der Message ersichtlich ist, warum man so formuliert, schliesslich kann man sich immer mal vertun und einen fehlerhaften Commit übermitteln und schnell korrigieren, aber ein ergänzender Hinweis wäre hier sicher nicht zu viel verlangt.

Stelle keine anderen Mitglieder bloß!

Solche Ansagen braucht keiner:

Fixed up heavy wrong typo, created by Beginner.
Keep crap like that out of the code base. 

Diese Art von Mitteilung ist nicht besonders hilfreich und so gesehen eine Frechheit. Womöglich geht man selbst recht oberflächlich mit seinen eigenen Commits um, aber teilt hier mal richtig aus. Also besser selbst an die eigene Nase fassen und Schreibenergie lieber in die eigenen Nachrichten stecken und lieber Hilfestellungen geben und Diskussionen auf gängigen Plattformen den Vorzug lassen. Du hast Code gefunden, der nur so vor Fehlern strotzte? Korrigiere ihn einfach und bleibe sachlich. Du warst auch mal Anfänger. Diese Commit-Nachricht wäre angemessener.

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

Kommunikation

Bei gewissen Sachverhalten, sollte man sich im gegenseitigen Austausch absprechen können, um kontroverse Ansichten auf einen Nenner zu bekommen und um vorab unpassende Commits zu vermeiden. Dies erfordert allerdings auch eine gewisse Kommunikations- und Kompromissbereitschaft innerhalb der Mitwirkenden eines Projekts. Nicht jeder Beteiligter ist immer mit demselben Thema beschäftigt und man muss sich vor Augen führen, dass nicht jeder über den gleichen Zeitrahmen und das Knowhow bei bestimmten Dingen verfügt. Hier kann die Kommunikation ins Stocken geraten, weil der eine oder andere evtl. ungeduldig werden könnte und sich womöglich, entweder spontan oder langfristig geplant, nur auf so einen Moment wartend, davon macht, um sein eigenes Ding zu machen. Eine ganz perfide Art dies zu verweigern wäre quasi ein Art Ghosting und/oder eine Kontaktverweigerung mit Ansage. Aus welchen Gründen auch immer, das wäre eine ziemlich schlechte Idee und kommt langfristig gesehen keinem zugute.

In Zeiten von Git, spielen Unterprojekte (Forks) eine gewisse Rolle, was bestimmte Vor- und Nachteile mit sich bringt. Je nach Seriosität und Wartungsgrad solcher Projekte, kann das eine wertvolle Bereicherung sein, aber gerade hier kann sich die benannte Kontaktverweigerung mit Ansage negativ auswirken und den Sinn des Ganzen kaputt machen. Man sollte daher den Zugewinn an Möglichkeiten, sich auszutauschen, nicht verspielen.

Kommunikation gegenüber Nutzern spielt sich insofern ab, als Ideen und deren schnelle Umsetzung gefordert werden, jedoch gibt es dafür oft verschiedene Lösungsansätze. In der Regel sind Nutzer oft daran interessiert, Wünsche schnell umgesetzt zu bekommen. Nutzer sehen aber oft nicht die sachlichen bzw. technischen Hintergründe. Bei gewünschten Übernahmen von Features ist es leider nicht immer mit einem einfachen Cherry-Pick aus verwandten Fork-Projekten getan, wenn dort schwer durchschaubare, unsaubere oder schlampige "Commit-Kultur" herrscht. Man sollte und kann daher nicht um jeden Preis allen Requests aus der Community bedingungslos nachkommen, nur weil dort ein nettes Feature drin ist, welches man auch gerne hätte. Übereifrige Übernahmen könnten thematische Überschneidungen in den Projekten von Kollegen verursachen und evtl. bessere Lösungsansätze kaputt machen, was zum Teil frustrierende Auswirkungen haben kann. Ständiges durchforschen, weil mal wieder nicht klar ist, was diese oder jene Änderung für Hintergründe hatte, weil nicht ersichtlich wird, ob diese Funktionen fehlerfrei, Nachbesserungen geplant oder nötig sind, tun ihr Übriges und sind nur einige Negativ-Beispiele. Brauchbare Lösungen und Konzepte lassen sich daher nur effektiv über Kommunikationswege vermitteln, auch hier sollte man die Wirksamkeit schlüssiger Commit-Nachrichten über Projektgrenzen hinaus nicht unterschätzen. Auch für zukünftige Dokumentationen sind diese Mitteilungen nachhaltige Informationsquellen und oft kann sich Kommunikation als Erstes um einen Commit entwickeln. Generell sind Commits mit aussagekräftigen Mitteilungen die erste Schnittstelle für Kommunikation und das sogar projektübergreifend. Commitmessages sollte man daher erst recht nicht vernachlässigen.

Langfristig gesehen, kann sich ein Projekt auch nur weiter entwickeln, wenn alles möglichst ausgewogen ineinander greift. Sollte man den Sinn einer Open-Source Gemeinschaft falsch verstanden haben oder der Meinung sein, sich unbedingt aus der Community hervorzutun, indem man versucht einem Projekt seinen ganz eigenen Stempel aufzudrücken, kann dies über kurz oder lang dazu führen, dass bestimmte Features, die nicht essenziell notwendig sind, gezielt gemieden werden und kein Austausch mehr erfolgt, was im Endeffekt zur völligen Inkompatibilität führen kann.

Wann comitten?

Lokal ist es ratsam seine Entwicklungsschritte abgetrennt in einem Branch und in einzelne Commits zu packen auch wenn diese zu einer Gesamtaufgabe gehören sollten. So kann man hier und da flexibel reverten oder weitere Branches ableiten, um Tests zu machen und wieder auf seinen Branch rebasen. Je nach dem wie man dann damit zufrieden ist, oder man der Meinung ist, das Ganze ist stimmig, kann man seine Commits zusammenfassen (Sichwort: git rebase -i) und als Patchsammlung verschicken bzw. als Entwickler auf den Entwicklungsbranch rebasen und ins Remote-Repo pushen.

Für Entwickler und überhaupt ist es durchaus ratsam nicht jeden anfallenden lokalen Commit druckfrisch in ein Remote-Repo zu schicken. Vorabtest sind durchaus angebracht. Gut "abgehangene" Commits, lassen sich lokal oft noch korrigieren und sinnvollerweise auf den Stand eines Remote-Repos rebasen und somit linear halten, denn oft findet man schon noch diesen oder jenen Bock, den man lieber vorher noch korrigieren sollte. Also sammeln ist insofern keine schlechte Idee.

Script zum Erstellen einer ChangeLog

Wenn man die Punkte von oben beachtet kann man mit diesem kleinen Script relativ schnell eine ChangLog Datei erstellen. Das Script ist recht rudimentär und ist sicherlich ausbaufähig und z.B. nur den ChangeLog zwischen zwei Commits oder Tags zu produzieren.

#!/bin/sh
# changelog.sh
# Convert git log to GNU-style ChangeLog file.
# (C) Chris
if test -d ".git"; then
    git log --date-order --date=short | \
    sed -e '/^commit.*$/d' | \
    awk '/^Author/ {sub(/\\$/,""); getline t; print $0 t; next}; 1' | \
    sed -e 's/^Author: //g' | \
    sed -e 's/>Date:   \([0-9]*-[0-9]*-[0-9]*\)/>\t\1/g' | \
#    sed -e ‘s/\(.*\)>Date: \([0-9]*-[0-9]*-[0-9]*\)/\2 \1>/g’ | \
    sed -e 's/^\(.*\) \(\)\t\(.*\)/\3    \1    \2/g' > ChangeLog
    exit 0
else
    echo "No git repository present."
    exit 1
fi

Das ergibt dann einen solchen Output:

8< ---
Carsten Schoenert <c.schoenert_at_t-online_dot_de>     2011-07-10

   openvpn: fixing wrong position of patch call in the target
   
   ups, a poor copy paste error :-(
   
   And one forgotten warning!
   You should't use your STB as a VPN Gateway from/to the Internet!
   Every process on the box is running the root previleges, so if someone
   has taken your box he will full access to your local lan!

Stefan Seyfried <seife_at_tuxbox-git_dot_slipkontur_dot_de>        2011-07-09

   improve nfsd init script to check exports syntax

Stefan Seyfried <seife_at_tuxbox-git_dot_slipkontur_dot_de>        2011-07-09

   glibc-pkg: add libnsl to package (needed by samba)

Carsten Schoenert <c.schoenert_at_t-online_dot_de>     2011-07-10

   openvpn: new target for *the* open source VPN software
   
   In the between times some people from the dark side there some quicker
   than I and make a usable make target for openvpn. I made some little
   modification for using it in my buildsystem. I added also the opkg build
   to the target.
   
   The opkg package may be usable, i did not tested it realy! The
   start/stop functionality is yet completely not implemented! So if you
   have some ideas for the correct implementation feel free to build it.
   
   So there is to copy the client.conf.example to /etc/openvpn, or even
   testing if there is some config, the loaded kernelmodul and so on.
   
   Remind:
   !!! You need the tun.ko kernelmodul to get proper working openvpn !!!

Stefan Seyfried <seife_at_tuxbox-git_dot_slipkontur_dot_de>        2011-07-03

   add debian-on-coolstream documentation
--->8