Proper Commit Nachrichten

Wofür sind Commit Nachrichten? Ich habe sie immer als Erklärung für das geschrieben, was ich getan habe, aber ich bin kürzlich in eine Diskussion darüber mit einem Kollegen geraten, der Commit-Nachrichten schreibt, in denen er erklärt, warum er es getan hat. Welcher hat Recht, oder gibt es noch eine andere Antwort?Proper Commit Nachrichten

HINWEIS: Ich habe absolut keine Ahnung, ob es eine "richtige" Antwort dafür gibt. Als solches habe ich es als Community-Wiki bezeichnet und werde keine Antwort akzeptieren. Upvotes soll den Gewinner entscheiden :)

Quelle

2010-06-10 Clark Gaebel

Als persönliche Präferenz kann ich sagen was getan wurde, indem Sie die Unterschiede in den Dateien direkt betrachten. Die warum ist die Sache, die ich nicht nur aus dem Blick auf die tatsächlichen Änderungen schließen kann.

Wenn die Änderungen signifikant oder kompliziert sind, dann würde ich nicht nur das Warum, sondern auch einen kurzen Überblick über die wie.

Quelle

2010-06-10 03:40:48

Ich sehe eine Commit-Nachricht als E-Mail. Das "Was" ist die Betreffzeile, die möglicherweise auf einen Fehler # verweist, aber die Änderung kurz beschreiben sollte Der Körper der Commit-Nachricht ist das Warum. –

Wenn man sich das Diff anschaut, sagt man * wie * es gemacht wurde, die Kommentare im Code und das Issue Tracking System sollten dir sagen * warum *, und die Commit-Nachricht sollte dir * was * sagen, vorzugsweise zusammen mit einem Link zu das Problemverfolgungssystem. Meiner Meinung nach natürlich. –

Manche Änderungen lassen sich nicht so leicht "Kommentare ... sollten Ihnen sagen warum" sagen: z. B. faulen Code löschen. Das Hinzufügen des "Warum" zu den Kommentaren könnte jedes Mal in einem SCM-in-Source-Code-Szenario enden. Zugegeben, manchmal macht es Sinn, einen Kommentar hinzuzufügen, der erklärt, warum der "offensichtliche" Ansatz, etwas Code hier hinzuzufügen, falsch wäre. –

Ich denke, beide sind nützlich. Eine kurze Beschreibung dessen, was geändert wurde ("Hinzufügen der Längenvalidierung für AddUserForm"), ist einfacher als das Betrachten eines Vergleichs, insbesondere wenn Sie mehrere Commits durchsuchen. Warum die Änderung gemacht wurde, welcher Fehler behoben wurde, etc. ist natürlich auch eine sehr gute Sache.

Quelle

2010-06-10 03:45:35

verwende ich die Commit-Nachricht als executive summary von was geändert wurde.

Die Zusammenfassung ist ein [...] kurzes Dokument, das [...] so zusammenfasst, dass Leser schnell eine große Menge von Material kennenlernen können, ohne alles lesen zu müssen.

Die warum woanders dokumentiert ist: Dokumentation ein Issue-Tracking-System, Anforderungen, usw. ich auch Links von der Commit-Nachricht an die warum, und vice versa.

Quelle

2010-06-10 03:46:03 Dolph

Warum ist wichtig - wenn Sie es nicht woanders dokumentieren, dann legen Sie es in die Commit-Nachricht. –

@theatrus, stimme ich absolut zu, aber für jedes mittelgroße Projekt, Commit-Nachrichten sind ** nicht ** der Ort, um Ihre * warum * zu dokumentieren. – Dolph

@Dolph, ich denke Commit-Nachrichten sind ein * toller * Ort, um Code-Whys zu setzen, aber ich stimme dir zu, dass es ein schlechter Ort ist, um Projekt-Warum zu setzen. Beispiel: "Dieser Code brach foo, weil er auf Bar segregierte": gut. "Diese Funktion wird benötigt, um Joe von Foo Inc. zu unterstützen": schlecht. –

Commit Nachrichten sind, was Sie von ihnen machen, aber wenn es Hunderte von ihnen für eine bestimmte Datei oder Tausende für ein Projekt gibt, möchten Sie in der Lage sein, durch sie auf bestimmte Änderungen oder die Art der Änderungen zu scannen . In der Tat sind sie wie Code-Kommentare, und sie müssen so hilfreich wie möglich, aber prägnant und prägnant sein. Vielleicht am besten, sie als Tweets zu betrachten - vermitteln maximale Bedeutung in einem kurzen Raum.

Als jemand, der an großen Codebasen über Jahrzehnte gearbeitet hat, und auch kleinere Projekte über ein Jahr oder zwei, habe ich nichts ärgerlicher beim Durchlaufen von Commit-Logs gefunden als Nachrichten wie "oops" oder "fixed bug". Wenn Sie einen Fehler behoben haben, sagen Sie uns, welcher (zumindest eine Fehlernummer). Es ist alles wichtig für die unvermeidliche Spurensicherung auf der Straße.

Quelle

2010-06-10 03:50:23 brainjam

Proper Commit Nachrichten

Antwort

Verwandte Themen