Hervorragende Git-Commit-Nachrichten verfassen: Best Practices für eine klare Historie

Git-Commit-Nachrichten sind die Notizen, auf die Ihr Team angewiesen ist, wenn Code bricht, sich das Verhalten ändert oder ein Release erklärt werden muss. Eine klare Nachricht sagt Ihnen, was sich geändert hat und warum, ohne dass Sie den Diff rückentwickeln müssen.

Gute Commit-Nachrichten müssen nicht ausgefallen sein. Sie brauchen eine nützliche Betreffzeile, genügend Kontext für nicht-triviale Änderungen und einen konsistenten Stil, den Ihr Team Monate später noch lesen kann.

Warum sind gute Commit-Nachrichten wichtig?

Gute Commit-Nachrichten helfen auf verschiedene praktische Weise:

Änderungen verstehen: Sie liefern sofortigen Kontext dafür, was ein bestimmter Commit einführt oder ändert, und sparen Zeit bei der Code-Überprüfung oder beim Nachvollziehen früherer Entscheidungen.
Debugging: Bei der Fehlersuche ermöglicht eine klare Commit-Historie, genau zu bestimmen, wann und warum eine problematische Änderung eingeführt wurde.
Zusammenarbeit: Für Teammitglieder, die zu einem Projekt stoßen oder alten Code wieder aufgreifen, erleichtern gut geschriebene Nachrichten das Verständnis des Entwicklungsverlaufs des Projekts.
Code-Reviews: Sie bieten Reviewern Einblick in die Absicht hinter den Änderungen und erleichtern so produktiveres und fokussierteres Feedback.
Automatisierte Tools: Viele Git-Tools, wie Changelog-Generatoren und Release-Notes-Ersteller, verlassen sich auf Commit-Nachrichten, um effektiv zu funktionieren.
Historische Aufzeichnung: Sie dienen als eine Form der Dokumentation, die die Entwicklung der Codebasis im Laufe der Zeit bewahrt.

Die Anatomie einer hervorragenden Git-Commit-Nachricht

Eine allgemein anerkannte Struktur für Git-Commit-Nachrichten folgt einem einfachen, aber leistungsstarken Muster: einer prägnanten Betreffzeile, gefolgt von einem optionalen, detaillierteren Textkörper.

Die Betreffzeile

Die Betreffzeile ist die erste Zeile Ihrer Commit-Nachricht. Sie sollte eine kurze, imperative Zusammenfassung der Änderungen sein. Betrachten Sie sie als Titel für den Commit.

Wichtige Richtlinien für die Betreffzeile:

Halten Sie sie prägnant: Etwa 50 Zeichen sind ein nützliches Ziel, keine harte Grenze. Halten Sie den Betreff kurz genug, um ihn in git log --oneline überfliegen zu können.
Verwenden Sie den Imperativ: Beginnen Sie mit einem Verb, das die Aktion beschreibt, als ob Sie einen Befehl erteilen würden. Beispiele: Fix, Add, Refactor, Update, Remove, Style.
Schreiben Sie das erste Wort groß: Die Standardkonvention schreibt vor, den ersten Buchstaben der Betreffzeile großzuschreiben.
Enden Sie nicht mit einem Punkt: Die Betreffzeile ist ein Titel, kein Satz.
Vermeiden Sie git commit -m "Nachricht" für längere Nachrichten: Obwohl praktisch für kurze Notizen, kann dies zu weniger strukturierten Nachrichten führen. Verwenden Sie git commit ohne Argumente, um Ihren Editor für komplexere Nachrichten zu öffnen.

Beispiele für gute Betreffzeilen:

feat: Benutzerauthentifizierungsmodul hinzufügen
fix: Endlosschleife in der Datenverarbeitung beheben
docs: README-Installationsschritte aktualisieren
refactor: Bildladen vereinfachen
chore: Entwicklungsabhängigkeiten aktualisieren

Der Textkörper

Der Textkörper der Commit-Nachricht ist der Ort, an dem Sie mehr Kontext und Details bereitstellen. Er wird durch eine Leerzeile von der Betreffzeile getrennt. Dieser Abschnitt ist optional, aber für alles andere als triviale Änderungen sehr empfehlenswert.

Wichtige Richtlinien für den Textkörper:

Erklären Sie das 'Warum' und 'Wie': Beschreiben Sie nicht nur, was sich geändert hat; erklären Sie, warum die Änderung notwendig war und wie sie implementiert wurde. Welches Problem löst dieser Commit? Was war das vorherige Verhalten? Was ist das neue Verhalten?
Zeilenumbruch bei 72 Zeichen: Dies ist eine langjährige Konvention, die die Lesbarkeit in vielen Git-Tools und Terminals verbessert.
Verwenden Sie Aufzählungspunkte für Listen: Wenn Sie mehrere Änderungen oder Punkte aufzählen müssen, verwenden Sie zur Klarheit Aufzählungspunkte.
Verweisen Sie auf Issues oder Tickets: Wenn der Commit mit einem Issue-Tracker (z. B. GitHub Issues, Jira) zusammenhängt, fügen Sie die Ticketnummer zur Nachvollziehbarkeit ein.

Beispiel einer guten Commit-Nachricht (Betreff + Textkörper):

feat: Benutzerprofilseite implementieren

Dieser Commit führt die Benutzerprofilseite ein, die es Benutzern ermöglicht,
ihre persönlichen Daten anzusehen und zu bearbeiten.

Zuvor konnten Benutzer nicht auf ihre Profildetails zugreifen oder sie ändern.
Diese Änderung fügt eine neue Route (`/profile`) und eine entsprechende
Komponente hinzu, die Benutzerdaten von der API abruft und Formulare
zum Aktualisieren von Feldern wie Name, E-Mail und Biografie bereitstellt.

Bezieht sich auf #123.

Häufige Commit-Nachrichtentypen (Conventional Commits)

Die Einhaltung einer Konvention für Commit-Nachrichtentypen kann die Klarheit weiter verbessern und automatisierte Werkzeuge ermöglichen. Die Conventional Commits-Spezifikation ist ein beliebter Standard, der einen strukturierten Ansatz fördert.

Conventional Commits verwenden ein Präfix, um die Art der Änderung zu kennzeichnen:

feat (Feature): Eine neue Funktion wird in die Codebasis eingeführt.
fix (Fehlerbehebung): Ein Fehler wird behoben.
docs (Dokumentation): Nur Änderungen an der Dokumentation.
style (Formatierung): Änderungen, die die Bedeutung des Codes nicht beeinflussen (Leerzeichen, Formatierung, fehlende Semikolons usw.).
refactor (Code-Umstrukturierung): Eine Codeänderung, die weder einen Fehler behebt noch eine Funktion hinzufügt.
perf (Leistung): Eine Codeänderung, die die Leistung verbessert.
test (Hinzufügen fehlender Tests oder Korrigieren vorhandener Tests): Hinzufügen oder Korrigieren von Tests.
build (Änderungen, die das Build-System oder externe Abhängigkeiten betreffen): Beispiele sind npm-Skripte, Webpack usw.
ci (Änderungen an unseren CI-Konfigurationsdateien und -Skripten): Beispiele sind Travis, Circle, BrowserStack, SauceLabs usw.
chore (Wartungsarbeiten): Aufgaben, die nicht in die anderen Typen passen, wie z. B. Repository-Haushalt.

Scope (Optional): Ein Scope kann zum Präfix hinzugefügt werden, um den betroffenen Teil der Codebasis anzugeben. Zum Beispiel: feat(auth): JWT-Authentifizierung hinzufügen.

Footer (Optional): Verwenden Sie den Footer, um auf Issues zu verweisen, Breaking Changes zu markieren oder andere Metadaten hinzuzufügen. Conventional Commits verwendet BREAKING CHANGE: für Breaking Changes.

Beispiel mit Conventional Commits:

fix(api): Endpunkt für Benutzerdatenabruf korrigieren

Zuvor gab der Endpunkt `/users/:id/data` veraltete Informationen zurück.
Dieser Commit aktualisiert den Endpunkt auf `/users/:id/profile`, der
die aktuellsten Benutzerprofildaten abruft.

Schließt #456

Tipps zum Verfassen großartiger Commit-Nachrichten

Häufig committen, aber logisch: Machen Sie kleine, atomare Commits, die eine einzelne logische Änderung darstellen. Dies macht Nachrichten leichter zu schreiben und zu verstehen.
Schreiben Sie Nachrichten aus der Perspektive des zukünftigen Selbst des Projekts: Stellen Sie sich vor, Sie sehen sich diesen Commit in sechs Monaten wieder an. Welche Informationen bräuchten Sie, um die Änderung schnell zu verstehen?
Seien Sie spezifisch: Vermeiden Sie vage Nachrichten wie "Code aktualisieren" oder "Fehlerbehebungen". Erklären Sie genau, was aktualisiert oder behoben wurde.
Verwenden Sie Backticks für Code-Referenzen: Wenn Sie Dateinamen, Funktionen oder Variablennamen erwähnen, setzen Sie sie in Backticks (`).
Überprüfen Sie Ihre Nachrichten: Bevor Sie committen, nehmen Sie sich einen Moment Zeit, um Ihre Nachricht zu lesen. Ergibt sie Sinn? Ist sie klar?

Fazit

Schreiben Sie jede Commit-Nachricht für die Person, die sie während eines Reviews, Rollbacks oder Vorfalls lesen wird. Verwenden Sie einen kurzen imperativen Betreff, fügen Sie einen Textkörper hinzu, wenn der Grund nicht offensichtlich ist, und halten Sie jeden Commit auf eine logische Änderung fokussiert.