Mein Lieblingsgit Commit

Hinweis perev. : Diese Veröffentlichung eines britischen Programmierers, der im englischsprachigen Internet zu einem echten Hit geworden ist, bezieht sich auf ein Git-Commit vor 6 Jahren. Es wurde in einem der offenen Repositories des staatlichen Digital Service aufgezeichnet - einem Dienst, der digitale Dienste in Großbritannien entwickelt und das GOV.UK-Projekt unterstützt. Das Commit selbst ist weniger interessant für Änderungen im Code als für die Beschreibung, die sie begleitet ...


Bild von xkcd # 1296

Ich liebe Commit-Beschreibungen in Git. Bei korrekter Verwendung können sie als eines der leistungsstärksten Werkzeuge zur Dokumentation der Entwicklung der Codebasis während ihrer Existenz bezeichnet werden. Ich möchte meinen Standpunkt am Beispiel meiner Lieblingsbeschreibung veranschaulichen.

Dieses Commit stammt aus meiner Zeit bei Government Digital Service. Der Autor ist ein Entwickler namens Dan Carley und hat einen eher unauffälligen Titel: " Die Vorlage wurde in US-ASCII konvertiert, um den Fehler zu beheben ."

"Ich habe mehrere Tests im Feature-Zweig implementiert, um den Inhalt von" / etc / nginx / router_routes.conf "abzugleichen. Sie funktionierten gut, wenn sie mit den Befehlen "bundle exec rake spec" oder "bundle exec rspec modules / router / spec" ausgeführt wurden. Aber wenn `bundle exec rake` ausgeführt wird, ist jeder Sollte-Block fehlgeschlagen:

ArgumentError: invalid byte sequence in US-ASCII 

Am Ende stellte ich fest, dass nach der Ausnahme vom Ausdruck ".with_content (//)" alle Fehler verschwinden. Dass die Spezifikationsdatei keine seltsamen Zeichen enthält. Und auch, dass es gespielt werden kann, indem Puppet im selben Interpreter aufgerufen wird:

  rake -E 'require "puppet"' spec 

Diese Vorlage scheint die einzige Datei in unserer Codebasis zu sein, die mit 'utf-8' codiert ist. Alle anderen Dateien in 'us-ascii':

  dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 

Ein Versuch, es in US-ASCII zu transkodieren, schlug aufgrund eines einzelnen Zeichens fehl, das wie ein Leerzeichen aussieht:

  dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert 

Nach dem manuellen Ersetzen wurde die Datei wieder zu 'US-ASCII':

  dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii 

Jetzt funktionieren die Tests! Die ganze Stunde meines Lebens kann nicht zurückgegeben werden ... "

Ein kleiner Exkurs: Einer der Vorteile der in GDS praktizierten Open Source-Entwicklung besteht darin, dass Sie Beispiele wie dieses außerhalb der Organisation, die sie erstellt hat, austauschen können. Ich weiß nicht, wer dieses Konzept zuerst der GDS vorgeschlagen hat - als ich der Organisation beitrat, war es bereits weit verbreitet -, aber ich bin dieser Person unendlich dankbar.

Warum ich dieses Commit mag

Unzählige Male habe ich es als Beispiel dafür angeführt, wozu Commit-Beschreibungen fähig sind. Es ist etwas lustig wegen des Verhältnisses der Änderungen im Code und der Größe der Beschreibung, aber ich mag es überhaupt nicht.

In einem anderen Unternehmen mit einem anderen Entwickler könnte die gesamte Nachricht des Commits auf Ausdrücke wie "Lücke ersetzen", "Fehler behoben" oder (je nach Teamkultur) auf Angriffe gegen den Erfinder untrennbarer Räume reduziert werden. Stattdessen nahm sich Dan die Zeit, um eine detaillierte Beschreibung zu erstellen, die für andere nützlich ist. Ich möchte auf die Gründe eingehen, warum ich dieses Engagement als ein wirklich gutes Beispiel betrachte.

Gibt den Grund für die Änderungen an

Die besten Beschreibungen von Commits geben nicht nur Auskunft darüber, was sich geändert hat, sondern erklären auch, warum . In unserem Fall:

Ich habe mehrere Tests im Feature-Zweig implementiert, um den Inhalt von `/ etc / nginx / router_routes.conf` abzugleichen. Sie funktionierten gut, wenn sie mit den Befehlen "bundle exec rake spec" oder "bundle exec rspec modules / router / spec" ausgeführt wurden. Aber wenn `bundle exec rake` ausgeführt wird, ist jeder Sollte-Block fehlgeschlagen:

  ArgumentError: invalid byte sequence in US-ASCII 

Ohne einen solchen Detaillierungsgrad könnten wir davon ausgehen, dass das Commit den Parsing-Fehler in einem bestimmten Tool korrigiert hat. Dank der Beschreibung des Commits wissen wir, um welches Tool es sich handelt.

Diese Art von Informationen kann sich als sehr wertvoll herausstellen und ist zu leicht zu verlieren, da die Leute dazu neigen, die Feinheiten ihrer Arbeit zu vergessen, zu anderen Teams zu wechseln und letztendlich das Unternehmen zu verlassen.

Gut zum Suchen

Eines der Schlüsselelemente dieser Beschreibung ist der Fehler selbst, mit dem weitere Suchen begannen:

ArgumentError:
ungültige Bytesequenz in US-ASCII

Jeder, der auf diesen Fehler stößt, kann die Codebasis durchsuchen, indem er entweder git log --grep "invalid byte sequence" oder die GitHub-Commit-Suche verwendet . Nach den Suchergebnissen zu urteilen, haben viele dies bereits getan und herausgefunden, wer und wann mit diesem Problem konfrontiert ist und wie es schließlich gelöst wurde.

Bietet ein vollständiges Bild

In der Festschreibungsnachricht wird angegeben, wie das Problem aussah, wie es untersucht und behoben wurde. Zum Beispiel:

Am Ende stellte ich fest, dass nach der Ausnahme vom Ausdruck ".with_content (//)" alle Fehler verschwinden. Dass die Spezifikationsdatei keine seltsamen Zeichen enthält. Und auch, dass es gespielt werden kann, indem Puppet im selben Interpreter angerufen wird.

Dies ist einer der Bereiche, in denen sich Nachrichten bei Commits wirklich zeigen können, da sie die Änderung selbst beschreiben und nicht irgendeine Datei, Funktion oder Codezeile. Dies macht sie zu einem großartigen Ort, um diese Art von zusätzlichen Code-Basis-Abenteuerinformationen zu speichern.

Macht alle ein bisschen schlauer

Dan hat hier eine Sache gemacht, die ich sehr schätze: alle Teams mitgebracht, die ich auf jeder Etappe gespielt habe. Dies ist eine großartige und kostengünstige Möglichkeit, Wissen in einem Team auszutauschen. Wenn Sie seine Beschreibung des Commits lesen, können Sie viel über Unix-Tools lernen:

• Sie können das Argument -exec , um einen Befehl für jede gefundene Datei auszuführen.
• Das Hinzufügen von \+ am Ende des Befehls bewirkt etwas sehr Interessantes (übergibt mehrere Dateinamen an den file und führt den Befehl nicht einmal für jede Datei aus).
• file --mime können file --mime den MIME-Typ der Datei ermitteln.
• Es gibt ein Dienstprogramm iconv .

Eine Person, die eine Beschreibung anzeigt, kann über all diese Dinge lernen. Jeder, der später über dieses Commit stolpert, wird auch etwas über diese Dinge erfahren. Wenn Sie diesen Ansatz für Commits für eine lange Zeit und eine ausreichende Anzahl von Commits multiplizieren, kann dies zu einem leistungsstarken Incentive-Helfer für das Team werden.

Entwickelt Empathie und Vertrauen

Jetzt funktionieren die Tests! Die ganze Stunde meines Lebens kann nicht zurückgegeben werden ...

Der letzte Absatz fügt ein Minimum an Menschlichkeit hinzu. Wenn man diese Worte liest, ist es schwierig, die Enttäuschung von Dan nicht zu spüren, der eine ganze Stunde lang nach einem versteckten Fehler suchen musste, und die Befriedigung, ihn zu korrigieren.

Stellen Sie sich nun eine ähnliche Nachricht vor, die an einen temporären Hack oder ein Fragment des Prototyp-Codes angehängt ist, der in Produktion ging und „Wurzeln schlug“ (wie dies bei solchen Fragmenten häufig der Fall ist). Diese Beschreibung des Commits erinnert alle daran, dass hinter jeder Änderung eine Person steht, die angesichts der zu diesem Zeitpunkt verfügbaren Informationen die bestmögliche Entscheidung trifft.

Gute Commits sind wichtig

Ich gebe zu, dass dies ein extremes Beispiel ist, und ich erwarte nicht, dass alle Commits (insbesondere in diesem Umfang) den gleichen Detaillierungsgrad aufweisen. Ich denke jedoch immer noch, dass dies ein großartiges Beispiel dafür ist, den Grund für die Änderung zu erklären, anderen zu helfen, neue Dinge zu lernen und zum kollektiven mentalen Modell beizutragen, das mit der Codebasis verbunden ist.

Wenn Sie mehr über die Vorteile einer guten Beschreibung von Commits und einige Tools erfahren möchten, die das Strukturieren von Änderungen vereinfachen, kann ich die folgenden Materialien empfehlen:

• " Geschichten erzählen durch Ihre Verpflichtungen " von Joel Chippindale;
• " Ein Zweig in der Zeit " von Tekin Süleyman.

PS vom Übersetzer

Lesen Sie auch in unserem Blog:

• „ Git passiert! 6 typische Git-Fehler und wie man sie behebt ";
• „Ein wunderbarer Trick, um einen Open Source-Projektbetreuer zum Tag zu machen “;
• „ Was haben große erfolgreiche Open Source-Projekte gemeinsam? ".