Formulierung
Eine der ersten Sachen, dass wir lernten, ist das Commit-Nachrichten im Imperativ geschrieben werden, nicht in der Vergangenheitsform. Das ist sinnvoll, weil die Nachricht das beschreiben soll, was das Commit tut, nicht was früher war. Das passt übrigens auch gut zu den Nachrichten, die git selbst generiert.
Format
Im Laufe der Zeit hat sich ein Format etabliert. Die Nachricht wird in zwei Bereiche aufgeteilt. Ein Betreff mit einer kurzen Bezeichnung, etwa 50 bis 70 Zeichen lang, wo wir deutlich angeben, was sich geändert hat. Dazu eine Beschreibung in den wir detailliert auf die Änderung eingehen. Sie werden mit einer Leerzeile voneinander getrennt. Das machen wir so, weil in vielen Fällen nur die erste Zeile angezeigt wird, der Rest der Nachricht nur bei Bedarf. Das erlaubt uns eine Kurzform der Änderung zu sehen, das ist oftmals ausreichend, um eine grobe Idee zu bekommen. Wenn wir mehr Details brauchen, schauen wir uns die Beschreibungen an.
Inhalt der Beschreibung
In der Beschreibung packen wir alles, was wir brauchen, um zu verstehen, was sich mit dem Commit ändert. Sie sollte so kurz wie möglich sein und so lang wie nötig. Informationen, die dazu gehören, sind:
Was ist das Problem? Was hat uns dazu geführt, die Änderungen vorzunehmen? Warum waren sie notwendig? Welche Funktionalität fügen wir hinzu und was ist der Mehrwert? Die Beantwortung diese Fragen zeigt uns das Was und das Warum. Das ist wichtig, um den Rahmen zu setzen.
Wie haben wir die Implementierung durchgeführt? Warum haben wir den Weg gewählt? Das ist wichtig. Dank daran: Obwohl es gerade klar ist, warum es so umgesetzt wird, kann es durchaus sein, dass in einigen Wochen es nicht mehr so eindeutig ist, vor allem wenn es jemand anders liest.
Hast du Seiteneffekte entdeckt? Dann solltest du sie erwähnen, um Fehlerquellen aus dem Weg zu gehen.
Gibt es offene Punkte? Auch das sind Informationen, die dazugehören. Am besten legen wir schon mal entsprechende Tickets an, die wir auch verlinken. Dazu erzähle ich euch gleich mehr. Wir stellen klar, dass die Änderung nicht voll abgeschlossen ist. Welche Verbesserungen kommen noch dazu?
Natürlich müssen nicht immer all diese Informationen dabei sein. Das sind halt nur ein paar Tipps und Richtlinien. Auf jeden Fall haben wir damit ein rundes Bild, ohne im Code nachzuschauen.
Ich fasse zusammen: In der Beschreibung schreiben wir alles, was wir brauchen, um die Änderung zu verstehen und ggf. Nachzuprüfen.
Das Wichtigste ist im Kopf zu behalten, dass die Informationen in der Commit-Nachricht für Menschen gedacht sind. Das ist das wichtigste Teil.
Wir dürfen natürlich auch weitere Daten angeben, wenn sie von Nutzen sind. Das kann zum Beispiel in Form von Verweise auf externe Systeme geschehen. Eine Verlinkung auf dem Ticket, welche die Änderung zugrunde liegt, ist ein guter Beispiel.
Hinter den Referenzen stecken bestimmte Informationen. Wenn sie wichtig sind, um die Änderung zu verstehen, nehmen wir sie in der Nachricht auf, weil wir nicht wissen können, ob die Menschen, die unsere Nachrichten lesen, Zugang zum externen System haben. Aber, was macht es für einen Sinn, die Referenz einzufügen, wenn wir den Inhalt sowieso in der Nachricht aufnehmen? Mir fallen zwei Gründe ein, um es zu tun.
Erstens. Es ist denkbar, dass die Informationen im Ticket viel detaillierter sind, als das, was wir im Commit angeben möchten. Denk daran: so kurz wie möglich … Zweitens: Auch wenn es nicht so ist, kann diese Referenz maschinell ausgewertet werden. Zum Beispiel durch ein Analysetool.
