Mein Lieblings-Git-Commit (2019)

Mein Lieblings-Git-Commit

• Die Bedeutung von Git-Commit-Messages wird hervorgehoben; sie gelten als eines der mächtigsten Werkzeuge, um eine Codebasis zu dokumentieren.
• Als Beispiel wird der von Entwickler Dan Carley verfasste Commit "Convert template to US-ASCII to fix error" herangezogen, um zu erklären, warum.
• Auf Grundlage von Erfahrungen beim GDS (Government Digital Service) wird erklärt, dass einer der Vorteile des öffentlichen Codens darin besteht, solche Beispiele auch außerhalb der eigenen Organisation teilen zu können.

Warum dieser Commit gut ist

• Das Verhältnis zwischen Commit-Message und Codeänderung ist zwar amüsant, aber das ist nicht der Grund, warum er als teilenswert gilt.
• In einer anderen Organisation oder von anderen Entwicklerinnen und Entwicklern hätte diese Commit-Message einfach als change whitespace oder fix bug zusammengefasst werden können.
• Stattdessen hat Dan sich die Zeit genommen, eine wirklich nützliche Commit-Message für die Menschen um ihn herum zu verfassen.

Er erklärt den Grund für die Änderung

• Die besten Commit-Messages erklären nicht nur, was geändert wurde, sondern auch, warum es geändert wurde.
• In diesem Commit wird ausführlich erklärt, warum ein eingeführter Test, der den Inhalt von /etc/nginx/router_routes.conf abgleichen sollte, beim Ausführen mit bundle exec rake mit dem Fehler ArgumentError: invalid byte sequence in US-ASCII scheiterte.
• Solche Informationen sind für die Dokumentation äußerst wertvoll und gehen leicht verloren, wenn Menschen den ursprünglichen Kontext vergessen, in andere Teams wechseln oder die Organisation verlassen.

Er ist durchsuchbar

• Im ersten Teil der Commit-Message steht die Fehlermeldung, die die Änderung ausgelöst hat. So kann jede Person in der Codebasis git log --grep "invalid byte sequence" ausführen oder die Commit-Suche auf GitHub verwenden, um nach diesem Fehler zu suchen.
• Tatsächlich konnten mehrere Personen nach diesem Problem suchen und herausfinden, wer es zuvor entdeckt hatte und wie damit umgegangen wurde.

Er erzählt eine Geschichte

• Die Commit-Message enthält Details dazu, wie sich das Problem gezeigt hat, wie die Untersuchung verlief und wie die Lösung zustande kam.
• Commit-Messages eignen sich hervorragend dafür, nicht ein bestimmtes File, eine Funktion oder eine Codezeile zu dokumentieren, sondern zusätzliche Informationen über den Weg festzuhalten, den die Codebasis genommen hat.

Er macht alle ein bisschen schlauer

• Dass Dan die in jedem Schritt ausgeführten Befehle dokumentiert hat, kann eine leichtgewichtige Methode sein, Wissen im Team zu teilen.
• Wer diese Commit-Message liest, kann dabei einige nützliche Tipps zum Unix-Toolset lernen.
• Sowohl Menschen, die diese Änderung reviewen, als auch Personen, die diesen Commit später finden, können daraus etwas mitnehmen.

Er baut Mitgefühl und Vertrauen auf

• Der letzte Absatz fügt einen menschlichen Kontext hinzu.
• Beim Lesen kann man Dans Frust darüber spüren, dass er eine Stunde damit verbracht hat, einen kniffligen Bug zu verfolgen, ebenso wie die Zufriedenheit darüber, ihn gelöst zu haben.
• Solche Commit-Messages helfen dabei, sich daran zu erinnern, dass hinter jeder Änderung ein Mensch steht, der versucht hat, die bestmögliche Entscheidung zu treffen.

Die Bedeutung guter Commits

• Dieses Beispiel ist ein Extremfall, und es wird nicht erwartet, dass jeder Commit dieses Maß an Detailtiefe hat.
• Dennoch ist es ein hervorragendes Beispiel dafür, den Kontext hinter einer Änderung zu erklären, anderen beim Lernen zu helfen und zum kollektiven mentalen Modell des Teams von der Codebasis beizutragen.
• Wer mehr über die Vorteile guter Commit-Messages und über Werkzeuge erfahren möchte, die dabei helfen, sie leichter zu strukturieren, dem seien Joel Chippindales "Telling stories through your commits" und Tekin Süleymans "A branch in time" empfohlen.

GN⁺-Meinung

• Dieser Artikel betont die Bedeutung von Git-Commit-Messages und zeigt, wie mächtig sie als Werkzeug sein können, um die Geschichte einer Codebasis zu dokumentieren und Wissen zu teilen.
• Dan Carleys Commit-Message ist in vielerlei Hinsicht ein vorbildliches Beispiel: Begründung der Änderung, Durchsuchbarkeit, Erzählen einer Geschichte, Wissensaustausch sowie der Aufbau von Mitgefühl und Vertrauen.
• Wenn Entwicklerinnen und Entwickler verstehen, wie wichtig gute Commit-Messages sind, und dieses Wissen in die Praxis umsetzen, können sie bessere Zusammenarbeit und Wartbarkeit des Codes erreichen, was wiederum zur Produktivität und Effizienz des gesamten Teams beiträgt.

[GN⁺]

Hacker-News-Kommentare

• Meinung des GitHub-Mitgründers:

  • Git-Commit-Messages sind eine einzigartige Form der Code-Dokumentation, aber nicht optimal.
  • Die meisten Tools zeigen nur die erste Zeile einer Commit-Message an.
  • Git hat Commit-Messages so entworfen, dass sie von allen Projektbeteiligten wie ein E-Mail-Text gelesen werden können, in der Praxis werden sie aber kaum angesehen.
  • Es ist auch schwierig, mit git blame die zugehörige Commit-Message zu finden.
  • Die Commit-Messages des Git-Projekts sind sehr detailliert, werden in der Praxis aber kaum genutzt.
  • Gute Dokumentation über Git zu schreiben, kommt in den meisten Communities fast einer Zeitverschwendung gleich.

• Die Bedeutung von Commit-Messages bei konkreten Problemen:

  • Die erste Zeile einer Commit-Message, die das Problem klar beschreibt, ist wichtig.
  • Bei Bedarf kann man den restlichen Teil lesen, um zusätzliche Informationen zu erhalten.

• Persönliche Gefühle zu Commit-Messages:

  • Es gibt Stolz darauf, großartige Commit-Messages zu schreiben, aber keine Gewissheit, ob sie für andere wirklich wertvoll sind.
  • Die meisten Menschen durchsuchen Commit-Messages fast nie.
  • Schöne Commit-Messages könnten Eitelkeit von Programmierern sein und möglicherweise keinen praktischen Wert haben.

• Strategie für die erste Zeile einer Commit-Message:

  • Bei der Verwendung von git log ist die erste Zeile am wichtigsten.
  • In der ersten Zeile sollte nicht stehen, was getan wurde, sondern warum es getan wurde.
  • Wie in einem Nachrichtenartikel ist es gut, die Informationen der Reihe nach von den wichtigsten bis zu den detaillierten anzuordnen.

• Die Schwierigkeit, Commit-Messages zu ändern:

  • Commit-Messages sind nach dem Schreiben schwer zu ändern.
  • Dokumente wie .md-Dateien, Wikis oder Confluence lassen sich leicht bearbeiten.
  • Man sollte der Versuchung widerstehen, das Design einer Komponente in einer Commit-Message zu erklären, und stattdessen bei Bedarf die Dokumentation verbessern.

• Die Bedeutung detaillierter Erklärungen bei kleinen Commits:

  • Je kleiner ein Commit ist, desto eher kann eine relativ lange Erklärung nötig sein.
  • Es ist wichtig, die Gründe für kleine Änderungen ausführlich zu erläutern.

• Grenzen von Commit-Messages und Probleme mit Tools:

  • Die erste Zeile einer Commit-Message sollte konkreter formuliert werden.
  • Die restliche lange Erklärung hat möglicherweise keinen großen Wert.
  • Es wird auf Probleme in Entwicklungswerkzeugen hingewiesen und gefordert, dass Fehlermeldungen klarer sein sollten.
  • Es wird infrage gestellt, warum Code-Editoren nicht standardisierte Leerraumzeichen zulassen.

• Die Bedeutung von Commit-Hygiene gegenüber Commit-Messages:

  • Wichtiger als detailreiche Commit-Messages ist eine gute Commit-Hygiene.
  • Saubere, unabhängige Commits machen es leicht, Code-Funktionalität herauszulösen und wiederzuverwenden.

• Kritik an Auto-Squash und Rebase:

  • Auto-Squash behindert das Schreiben aussagekräftiger Commit-Messages.
  • Rebase ist dafür da, dass Entwickler bewusst aufräumen, und sollte nicht zum Standardmuster beim Mergen werden.