Wie man eine GROSSE Git Commit Nachricht schreibt

Einführung

Das Verfassen effektiver Git-Commit-Nachrichten kann die Zusammenarbeit, die Lesbarkeit des Codes und die Wartbarkeit des Projekts über Jahre hinweg erheblich verbessern. Dennoch wird es oft übersehen oder als nachträglicher Gedanke im Entwicklungsprozess behandelt. In diesem Blogbeitrag bringe ich es auf den Punkt und erläutere die wichtigsten Grundsätze für das Schreiben hervorragender Git-Commit-Nachrichten, die jeder Entwickler befolgen sollte!

1. Beginnen Sie mit einem großgeschriebenen imperativen Verb in der Betreffzeile

Eine Commit-Nachricht sollte klar angeben, was dieser Commit bewirkt. Verwenden Sie ein großgeschriebenes imperatives Verb am Anfang, um die Lesbarkeit und Wartbarkeit zu erleichtern.

Beispiel

• hinzufügen neue Funktion für die Benutzeranmeldung

• Behebung Fehler in der Zahlungsabwicklung

• Aktualisierung Dokumentation für API-Endpunkte

2. Behalten Sie die Betreffzeile kurz und bündig

Ihre Commit-Nachricht sollte beschreibend genug sein, um den Zweck des Commits zu vermitteln, aber kurz genug, um schnell überflogen zu werden. Die Betreffzeile sollte etwa 50 Zeichen lang sein, während der Text zusätzliche Details enthält.

• Gute Commit-Meldung: Überarbeitung des Moduls zur Benutzerauthentifizierung

• Schlechte Commit-Meldung: Das Modul zur Benutzerauthentifizierung wurde überarbeitet, um die Leistung und Lesbarkeit zu verbessern

3. Trennen Sie die Zusammenfassung durch eine Leerzeile vom Hauptteil

Wenn Ihre Commit-Nachricht mehr Details benötigt, fügen Sie einen Textkörper hinzu. Achten Sie darauf, eine Leerzeile zwischen der Zusammenfassung und dem Hauptteil einzufügen, um die Lesbarkeit zu verbessern.

Hinzufügen von lokalem Caching zur Verbesserung der Anwendungsleistung

Mit dieser Änderung wird ein lokaler Caching-Mechanismus implementiert, um die Datenbanklast
und die Antwortzeiten über das Netzwerk zu verbessern. Der Cache wird alle zehn Minuten ungültig gemacht, um die Aktualität der Daten zu gewährleisten.

4. Verwenden Sie den Imperativ

Behalten Sie die Standardkonvention im Hinterkopf und schreiben Sie Commit-Nachrichten im Imperativ, einer Zeitform, die normalerweise mit Befehlen und Aktionen assoziiert wird. Dies ist eine Anweisung darüber, was getan wird, wenn die Übergabe durchgeführt wird.

Beispiele:

• Richtig: hinzufügen. Benutzerauthentifizierung

• Falsch: Hinzugefügt Benutzer-Authentifizierung

• Korrigieren: Fix Benutzerauthentifizierung

• Falsch: Behoben Benutzerauthentifizierung

• Richtig: Aktualisieren Sie Benutzerauthentifizierung

• Falsch: Aktualisiert Benutzerauthentifizierung

5. Erklären Sie das "Was" und "Warum" im Textkörper

Verwenden Sie den Hauptteil, um den Commit detaillierter zu beschreiben: Erklären Sie, was getan wurde und warum es getan wurde. Das macht es für andere - und für Sie selbst in Zukunft - einfacher, den Kontext und den Grund für die Änderung zu verstehen:

• Was: Überarbeitung der Authentifizierungslogik

• Warum: Verbesserung der Leistung und Reduzierung von Code-Duplikaten

Beispiel:

Überarbeitung der Authentifizierungslogik

Die Authentifizierungslogik wurde aus einer Klasse in ein separates Modul ausgelagert, um die Leistung zu verbessern und Code-Duplizierung zu vermeiden. Diese Änderung
wird auch die Implementierung zukünftiger Erweiterungen erleichtern.

6. Aufzählungspunkte für Listen verwenden

Wenn der Commit mehrere Änderungen enthält, sollten Sie diese in Aufzählungspunkten auflisten. Dies erleichtert das Lesen und Verstehen der einzelnen Änderungen:

Verbesserung der Fehlerbehandlung bei der Zahlungsabwicklung

- Validierung für Zahlungseingabefelder hinzufügen
- Behandlung von API-Fehlern mit Wiederholungsmechanismus
- Protokollierung detaillierter Fehlermeldungen für die Fehlersuche

7. Verweis auf relevante Fragen oder Tickets

Wenn Ihr Commit ein bestimmtes Problem oder eine bestimmte Aufgabe löst oder damit zusammenhängt, referenzieren Sie es in Ihrem Projektmanagementsystem, z. B. GitHub Issues oder Jira. Dies hilft, den Status der Issues auf dem neuesten Stand zu halten, und der Kontext wäre für die Leser später sehr hilfreich.

Fehlerhafte Gesamtberechnung korrigiert (#4342)

Die Berechnungslogik für Bestellsummen wurde korrigiert, um sicherzustellen
Steuern und Rabatte angewendet werden.

8. Überprüfung und Überarbeitung

Nehmen Sie sich einen Moment Zeit, um Ihre Nachricht zu überprüfen, bevor Sie sie festschreiben und an das Repository weiterleiten. Überprüfen Sie sie auf Rechtschreib- und Grammatikfehler sowie auf ihre Klarheit. Eine gut geschriebene Commit-Nachricht zeugt von Professionalität und Liebe zum Detail, was im weiteren Verlauf Zeit und Kopfschmerzen sparen kann.

Schnell-Checkliste

• Groß schreiben: Haben Sie Ihre Betreffzeile mit einem Großbuchstaben begonnen?

• Kurz und bündig: Ist Ihre Betreffzeile 50 Zeichen oder weniger lang?

• Leere Zeile: Haben Sie eine Leerzeile nach der Zusammenfassung eingefügt, wenn es einen Hauptteil gibt?

• Imperative Stimmung: Ist die Nachricht im Imperativ verfasst?

• Ausführlich: Erklärt die Stelle (falls vorhanden) das Was, Warum und Wie?

• Listen: Haben Sie Bullet Points für Ihre Liste verwendet?

• Referenzen: Haben Sie sich auf relevante Themen oder PRs bezogen?

• Korrekturlesen: Haben Sie auf Klarheit und Tippfehler geachtet?

Schlussfolgerung

Das Schreiben guter Git-Commit-Nachrichten verbessert die Zusammenarbeit und die Wartbarkeit des Projekts. Wenn Sie diese einfachen Richtlinien befolgen - imperative Verben verwenden, den Betreff prägnant halten, das "Was" und "Warum" erklären und auf relevante Probleme verweisen - erstellen Sie eine wertvolle Projekthistorie, die leicht zu navigieren und zu verstehen ist. Wir haben auch einen anderen Beitrag mit dem Titel "3 Gründe, warum Sie konventionelle Commits verwenden sollten" wenn Sie mehr darüber erfahren möchten.

Wir würden uns auch freuen, wenn Sie sich uns auf dem Vonage Community Slack oder senden Sie uns einen Post auf X und wir werden auf Sie zurückkommen. Nochmals vielen Dank fürs Lesen, und wir sehen uns beim nächsten Mal wieder!

Viel Spaß beim Begehen!