Was sollte ich beim Festschreiben der Quellcodeverwaltung in Kommentare einfügen?

Ich bin ein Einzelentwickler und unterhalte einen SVN-Server für die Quellcodeverwaltung. Bisher habe ich beim Festschreiben meiner Änderungen nichts Bestimmtes befolgt.

Ich habe gerade meine vorherigen Commits überprüft und konnte aus meinen Kommentaren keinen Sinn machen.

Was geben Sie beim Festschreiben Ihrer Checkins in die Kommentare ein?

Vielleicht möchten Sie dies lesen: /programming/321720/best-practices-for-version-control-comments .

Wenn Sie keinen Bug-Tracker verwenden und daher keine ID / Nummer für den Fehlerbericht enthalten können, müssen Sie in Ihren Kommentaren sehr aussagekräftig sein. Andernfalls können Sie sich zwei Wochen nach dem Festschreiben nicht daran erinnern, was das Problem war, wenn Sie beispielsweise "Behobenes Problem mit X" schreiben. In diesem Fall müssen Sie die Versionen vor und nach dem Festschreiben vergleichen, um zu verstehen, was es war.

Als ich anfing, Anwendungen professionell zu entwickeln, haben wir keinen Bug-Tracker verwendet, und ich kann mich daran erinnern, dass Kommentare manchmal sehr beschreibend waren (zu viel sogar), manchmal gab es überhaupt keinen Kommentar, es war ein Durcheinander. Mit einer Bug-Tracker-ID sind Kommentare viel nützlicher und mit ein paar weiteren Worten können Sie sogar angeben, warum Sie diese bestimmte Änderung vorgenommen haben. IDEs wie beispielsweise Eclipse verfügen über Plugins, die die IDs des Bug-Trackers in Kommentaren (und auch im Quellcode) erkennen und einen anklickbaren Link zur Webseite des Bug-Trackers bereitstellen können.

Was haben Sie in den Kommentaren Ihrer vorherigen Commits erwartet?

Fügen Sie diese Informationen einfach in Ihre nächsten Commits ein.

Manchmal reicht eine Ticket-ID aus, ein Ticket, das einen Fehlerbericht oder eine Funktionsanforderung darstellt.

Bei Commit-Kommentaren geht es darum, leicht zu erkennen, was geändert wurde. Sie dienen als Referenz. Wie viele Details Sie in sie einfügen, hängt also davon ab, wie viel Aufwand Sie jetzt aufwenden möchten, um in Zukunft Zeit zu sparen. Im Allgemeinen kann ein geringer Aufwand an Festschreibungszeit in Zukunft viel Zeit sparen.

Angenommen, Sie haben in einer Schleife a <=in a >und a ++in a geändert --, aber keinen beschreibenden Commit-Kommentar hinzugefügt. Später ist es schwierig, die Revision zu finden, bei der Sie die Richtung der Iteration umgekehrt haben. Wenn Sie " Umgekehrte Richtung des blauen Indexdurchlaufs " kommentiert hätten, wäre es viel einfacher, diese Revision zu finden, indem Sie das Revisionsprotokoll durchsuchen.

Aus diesem Grund ist es eine gute Idee, Informationen zur Problemverfolgung in Festschreibungsnachrichten aufzunehmen. Angenommen, Sie beheben einen Fehler. Später wird das Problem erneut geöffnet, da es nicht vollständig behoben wurde. Wenn in Ihrem Commit-Kommentar zum ursprünglichen Fix die Problem-Tracker-ID erwähnt wurde, können Sie sie leicht finden und später können Sie alle mit diesem Problem verbundenen Revisionen leicht finden.

Ich neige dazu, eine kurze Form von dem zu schreiben, was ich begebe; Wenn es sich um eine bestimmte Aufgabe handelt, füge ich die Aufgabennummer in die Nachricht ein. Dinge wie:

Changed foobar module to account for the new baz; created quux pages and data objects.

Was Sie nicht tun sollten, ist einen Unsinn wie "Ups" oder "Hinzugefügte Kommentare" zu schreiben (beide wurden von einem Kollegen in den Festschreibungsprotokollen hinzugefügt) oder am schlimmsten etwas zu tun, wie ich es neulich gesehen habe - A. Eine einzelne Datei wurde mit der Festschreibungsmeldung "Kommentar" (genaues Anführungszeichen) eingecheckt. Was wurde hinzugefügt, fragen Sie sich vielleicht? Etwas zu bewirken von:

if (z == true) { 
    x = y; // x is being overridden here... <--- added in commit
}

Und nein, wir werden nicht an der Anzahl der Commits gemessen.

Ich denke, das alles läuft darauf hinaus, wie Sie Ihre Projekte verwalten. Für mich tendiere ich dazu, mich zu verpflichten, wenn ich eine Funktion beende, die ich auf einen Release-Build übertragen möchte. Da in meinem Fall jedes Feature zu einem Commit führt, verwende ich die Story und die Ausgabenummer meines Features als Kommentar. Gleiches gilt für die Behebung von Fehlern. Ich beginne mit einem Spike, leite eine Story ab, beschreibe anhand der Story die Änderungen, die ich vornehmen muss, und verpflichte mich erneut zur Quellcodeverwaltung mit einer Story in den Kommentaren.

Problem-ID.

Die meisten Issue-Tracker haben ein Format, mit dem sie Issue-IDs aus Commit-Nachrichten analysieren und Commits mit Problemen gruppieren können.

Wenn Sie keinen Issue-Tracker verwenden, sollten Sie, es spielt keine Rolle, ob Sie ein Solo-Entwickler sind. Ich habe die Angelegenheit anhand einer anderen Antwort erläutert :

Verwenden Sie einen Issue-Tracker. Es spielt keine Rolle, dass Sie ein einsamer Wolf sind. Behalten Sie alles im Auge, was Sie für Ihr Projekt tun, ob es sich um eine Funktion oder einen Fehler handelt. Erstellen Sie eine Feature- / Komponentenliste. Markieren Sie wirklich wichtige Komponenten als Version 1.0 und alle anderen als Version 2.0. Und löschen Sie dann alles, was als 2.0 markiert ist.

Ok, da die Frage eine Mod-Benachrichtigung für längere Antworten erhalten hat, fühle ich mich verpflichtet zu erweitern:

Ja, ich habe nur die Problem-ID in Commit-Kommentare eingefügt, sonst nichts. Bei Soloprojekten ist es bei Teamprojekten eine ganz andere Geschichte. Ich befürworte nicht , nur die Problem-ID zu setzen, es sollte etwas mehr da sein, aber:

1. Bei Soloprojekten ist es äußerst verlockend, nichts zu dokumentieren.
2. Wenn Sie die Problem-ID eingeben, haben Sie standardmäßig einen Problem-Tracker eingerichtet.
3. Das ist gut genug für mich.

Die effektive Verwendung eines Issue-Trackers bei der Entwicklung von Solo ist eine weitaus größere Leistung als das Festschreiben von Kommentaren. Es wäre schön, wenn ich die Motivation hätte, etwas Hilfreiches in die Kommentare aufzunehmen, aber das tue ich nicht.

Im Allgemeinen habe ich den Zweck des Check-ins ganz oben angegeben. Dies kann der Name einer Funktionsanforderung, eine Ticketnummer usw. sein.

Anschließend füge ich die Liste der betroffenen Dateien und die spezifischen Änderungen hinzu, die in jeder Datei erforderlich sind. Dies ist besonders hilfreich, wenn Sie den Revisionsverlauf einer Datei im Gegensatz zum Projekt / Ordner betrachten.

Etwas wie

Ticket 101 fix web service exception when uploading widget

Bug was caused by users uploading incomplete widgets (widgets without wonkers)

webservice.cs:  
  improved post validation for incomplete widgets
  added default exception handler to ProcessWidget
widget.cs:  handled the SqlException when inserting widgets without wonkers

Im Allgemeinen ist das, woran Sie in diesem Commit gearbeitet haben, ein guter Anfang :)

(Aus Neugier ... was hast du geschrieben, wenn du keinen Sinn daraus machen konntest?)

Die Änderungen, die Sie am Code vorgenommen haben, und was auch immer relevant sein könnte, einschließlich Fehlerbehebungen, neue Funktionen, Funktionsunterbrechungen, Änderungen in Bibliotheken usw. Natürlich, da der Code in kleinen Schritten festgeschrieben wird wird nicht alle oben haben. Wenn Sie beispielsweise einen Fehler beheben, können Sie mehrere Änderungen vornehmen. Dies sind mehrere Commits, um den Fehler zu beheben, aber welche Änderungen Sie vorgenommen haben, um den bestimmten Fehler zu beheben.

Die wichtigste Information im Festschreibungsprotokoll ist das "Warum", nicht das "Was".

Eine kurze Zusammenfassung der Änderungen kann nützlich sein, aber normalerweise können Sie diese Informationen vom Diff selbst erhalten. Es ist kein großes Problem, wenn das fehlt.

Wenn Sie auf ein Festschreibungsprotokoll zurückblicken, möchten Sie wissen, warum diese Änderung vorgenommen wurde. Eine Fehler-ID kann einen großen Beitrag zur Beantwortung dieser Frage leisten. Manchmal sind weitere Erklärungen erforderlich. Wenn Sie beispielsweise ein Problem bei einer fehlerhaften Eingabe beheben, erklären Sie, welche Eingabe das Problem verursacht hat, und wenn es nicht trivial ist, wie es auftreten kann.

Wir verwenden Assembla für unser Projekt. Wir bauen die Kartenwand mit allen Merkmalen / Fehlern, die behoben werden müssen, und beziehen uns beim Festschreiben nur auf dieses Ticket

Zum Beispiel:

see #243
 - Grid listed all users with an income more then 1000$ but not the ones that have
   exactly 1000. Added a >= in the file xy.cs on the line xyz

Auf diese Weise können wir die Änderungen schneller lokalisieren und einige Fehler leichter finden