Mit Sicherheit ist jeder schon einmal über Commits gefallen, aus denen er nicht
schlauer wurde. Häufig liegt das an vagen, kurzen Aussagen in Commit Messages
wie z.B. Anpassungen
oder Diverse Änderungen
.
Hier stelle ich ein paar Angewohnheiten vor, die meine Commit History davor bewahren, so zu enden wie in diesem XKCD:
Dies sind alles Meldungen, die wenig bis garkeine nützlichen Informationen
enthalten.
Die dargestellte Extreme habe ich zwar noch nicht gesehen, aber auch hier
finden wir den Klassiker Code Additions/Edits
. Überflüssiger kann es nicht
sein: Dass irgendetwas hinzugefügt (oder gelöscht) bzw. angepasst wurde, ist
selbsterklärend. Andernfalls hätte der Autor wohl kaum die Versionskontrolle
bemüht.
It’s all fun and games until nobody has any idea what the hell is going on. – @ThePracticalDev
Was den Leser (dazu gehört auch das zukünftige Selbst!) vor allem interessiert, ist, warum diese Änderungen gemacht wurden, weshalb welche Entscheidungen getroffen wurden.
Einen ersten Hinweis darauf kann unter anderem eine Ticketnummer liefern. So lässt sich dann evtl. über Ticketsystem/Issue-Tracker nachvollziehen, was die Intention war.
Ohne weitere Informationen kann schonmal ein wenig Zeit verloren gehen: Tickethistorie muss studiert, die konkreten Änderungen müssen analysiert, Kollegen konsultiert werden usw.
Template
Um diesen Problemen entgegenzuwirken, schreibe ich Commit-Messages etwa nach dem Muster, wie es Tim Pope in seiner Note About Commit Messages vorschlägt:
<Ticketnr.> Kurze beschreibung, *was* geändert wurde
Nach einer Leerzeile folgen dann Erläuterungen, *warum* die Änderungen
gemacht wurden und was sie bewirken. Dabei versuche ich 80 Zeichen
nicht zu überschreiten.
Weitere Absätze folgen nach weiteren Leerzeilen.
- Die Ticketnummer ist hier optional und hängt i.d.R. auch vom jeweiligen Projekt ab.
- Die einleitende Betreff-Zeile soll kurz zusammenfassen, was geändert wurde. Diese Zeile ist die, die in den Logs angezeigt wird. Details sind meist nicht weiter nötig. Die können wenn nötig z.B. mit diff-Tool abgefragt werden.
- Der weitere Teil sollte dann erklären, warum welche Entscheidungen getroffen wurden, wie sich das neue zum alten Verhalten unterscheidet usw.
Im Gegensatz zu Tim Pope, der für den Betreff ~50 und für Erläuterungen <72
Zeichen je Zeile ansetzt, erlaube ich es mir, für beides max. 80 Zeichen
zu verwenden.
Tim führt dabei (April 2008) die Lesbarkeit in der Konsole an. Das entspricht
jedoch weniger meinem Workflow: Wenn ich Logs durchstöbere, nutze ich dafür in
der Regel lieber eine bequeme GUI. Außerdem sind die meisten Konsolen - z.B.
auch PowerShell - nicht (mehr) auf 80 Spalten begrenzt.
Warum halte ich mich dennoch an 80 Zeichen? Ergonomie: Auch wenn Monitore und Tools mehr Platz für weitaus längere Zeilen bieten, lässt sich Text dennoch einfacher erfassen, wenn er in der Breite begrenzt ist.
Zusätzlich formatiere ich die Messages, wenn nötig, mit Markdown. Z.B.: *
für
Bullet Points und `` für Code, etc.
Babysteps
Babysteps halte ich eigentlich aus anderen Gründen für eine sinnvolle Vorgehensweise. Doch gerade für das schreiben von Commit Messages sind sie sehr wertvoll.
Diverse Änderungen
gehen sehr oft, mit Monster-Commits einher, In denen
viel Code geändert wurde. Alternativ gibt es zahlreiche aufeinanderfolgende
Commits mit der gleichen Message.
Eine Ursache dafür ist, dass Entwickler scheinbar den Überblick darüber verlieren, was sie genau und aus welchem Grund geändert haben. Dann scheint der Aufwand zu groß, die Details aufzuschlüsseln.
Mit Babysteps committe ich häufig kleine Änderungen und kann sie detailliert erklären. Mit Git halte ich es manchmal so, dass ich mehrere einzelne Commits, die zusammengehören zu einem einzigen zusammenfasse bevor ich pushe. Dadurch kann ich auch größere Commits mit genügend Details versehen.
Fazit
Das tatsächliche Format von Commit-Messages ist sicherlich Geschmacksache und hängt auch davon ab wie man mit den Logs arbeitet oder sie aufbereitet. Generell macht es das Schreiben von guten Commit-Messages jedoch einfacher, wenn man eine Vorlage hat, an der man sich orientieren kann.
Wer dazu in kleinen Schritten vorgeht, läuft weniger gefahr, Details seiner Änderungen beim Committen zu vergessen. Das hilft dem Team und erweckt nicht den Eindruck, als wüsste man nicht, was man eigentlich macht.
Wie schreibst du (bzw. dein Team) Commit Messages? Gibt es Meldungen, die dir besonders auffallen?
Resourcen
- A Note About Commit Messages, Tim Pope (2008)
- “Lightning Talk: Do Your Commit Messages Suck” by: Ryan McGeary