Sollte ich Vergangenheits- oder Gegenwartsform in Git-Commit-Nachrichten verwenden? [geschlossen]

531

Ich habe einmal gelesen, dass Git-Commit-Nachrichten im Imperativ Präsens sein sollten, z. B. "Tests für x hinzufügen". Ich verwende immer die Vergangenheitsform, z. B. "Tests für x hinzugefügt", was sich für mich viel natürlicher anfühlt.

Hier ist ein kürzlich von John Resig vorgenommenes Commit, das die beiden in einer Nachricht zeigt:

Optimieren Sie einige weitere jQuery-Set-Ergebnisse in den Manipulationstests. Außerdem wurde die Reihenfolge der erwarteten Testergebnisse festgelegt.

Ist das wichtig? Welches soll ich verwenden?

Skilldrick
quelle
12
Diese Frage muss daher als primär meinungsbasiert geschlossen werden . Schauen Sie sich nur die Meinungsverschiedenheiten zwischen Imperativ und Vergangenheitsform an ! Davon abgesehen stimme ich für die Imperativform, weil es wirklich hilft zu klären, was Sie tun, wenn Sie Ihre Geschichte neu schreiben, Kirschen pflücken, Patches anwenden usw.!
3
@Eonil Wenn es geschlossen ist, um hier meinungsbasiert zu sein, wird es geschlossen, weil es dort auch meinungsbasiert ist.
Ratschenfreak

Antworten:

601

Die Präferenz für Commit-Nachrichten im Präsens-Imperativ-Stil kommt von Git selbst. Aus Documentation / SubmissionPatches im Git-Repo:

Beschreiben Sie Ihre Änderungen in der imperativen Stimmung, z. B. "xyzzy do frotz machen" anstelle von "[Dieser Patch] macht xyzzy do frotz" oder "[I] hat xyzzy in frotz geändert", als ob Sie der Codebasis befehlen, ihre zu ändern Verhalten.

Sie werden also viele Git-Commit-Nachrichten sehen, die in diesem Stil geschrieben wurden. Wenn Sie in einem Team oder an Open Source-Software arbeiten, ist es hilfreich, wenn sich alle aus Gründen der Konsistenz an diesen Stil halten. Selbst wenn Sie an einem privaten Projekt arbeiten und der einzige sind, der jemals Ihre Git-Geschichte sehen wird, ist es hilfreich, die imperative Stimmung zu verwenden, da sie gute Gewohnheiten festlegt, die geschätzt werden, wenn Sie mit anderen zusammenarbeiten.

Mipadi
quelle
90
Ich denke, das ist eine ausgezeichnete Wahl. Überlegen Sie, was ein Commit in unterschiedlicher Form ist: eine Reihe von Anweisungen, wie Sie von einem vorherigen Status in einen neuen Status wechseln können. So wie der Diff sagt "Diese Zeile hier hinzufügen, diese Zeile hier entfernen", heißt es in der Festschreibungsnachricht qualitativ "Diese Änderung vornehmen". (Ja, Git speichert das Commit einfach als Baum mit Metadaten, aber für einen Menschen ist der Unterschied der wichtige Teil eines Commits.)
Cascabel
124
Möglicherweise sehen Sie ein Commit als eine Reihe von Anweisungen, wie Sie vom vorherigen zum neuen Status wechseln können. aber ich sehe es eher als Kontrollpunkt in der Entwicklung des Codes. Für mich ist die Festschreibungsnachricht ein Protokoll darüber, was seit dem vorherigen Festschreiben mit dem Code geschehen ist. und für ein Protokoll ist Vergangenheitsform viel sinnvoller. Wenn Sie wirklich der Meinung sind, dass die Festschreibungsnachricht eine Reihe von Anweisungen sein sollte, ist die Imperativform der richtige Weg. Ich denke einfach nicht so darüber nach.
Karadoc
10
@oschrenk: Spätere Versionen der Datei haben einen Grund angegeben: "Beschreiben Sie Ihre Änderungen in der imperativen Stimmung, z. B. 'xyzzy do frotz machen' anstelle von '[Dieser Patch] macht xyzzy do frotz' oder '[I] hat xyzzy in frotz geändert ', als ob Sie der Codebasis befehlen, ihr Verhalten zu ändern. "
Mipadi
44
Die Festschreibungsnachricht sollte zwingend und in der Gegenwart sein, da Sie oder jemand anderes mit git möglicherweise etwas tun rebaseoder cherry-pickin diesem Fall die Festschreibung außerhalb des ursprünglichen Kontexts verwendet werden kann. Infolgedessen sollte die Festschreibungsnachricht eigenständig geschrieben werden, ohne dass der Leser die umgebenden Festschreibungsnachrichten anzeigen muss. Wenn Sie Patches für die Kirschernte auswählen, ist es sinnvoller, "QuickSort-Algorithmus korrigieren" oder "Sortieren: Leistung verbessern" anstelle von "Behobener Fehler Nr. 124" oder "Geänderte Sortierung zur Verbesserung der Leistung" anzuwenden.
Mikko Rantalainen
5
Ich denke darüber nach, dass die Nachricht mir mitteilen sollte, was sich ändern wird, wenn ich dieses Commit auf meinen Zweig anwende. Ich betrachte es nicht als Protokoll, sondern als Zustände, in den ich wechseln kann, und ich muss wissen, was passieren wird, wenn ich einen bestimmten Zustand auswähle.
Steinybot
357

Ihr Projekt sollte fast immer die Vergangenheitsform verwenden . In jedem Fall sollte das Projekt aus Gründen der Konsistenz und Klarheit immer dieselbe Zeitform verwenden.

Ich verstehe einige der anderen Argumente, die argumentieren, die Gegenwart zu verwenden, aber sie treffen normalerweise nicht zu. Die folgenden Aufzählungspunkte sind häufige Argumente für das Schreiben in der Gegenwart und meine Antwort.

  • Das Schreiben in der Gegenwart sagt jemandem, was das Anwenden des Commits bewirken wird , anstatt was Sie getan haben.

Dies ist der richtigste Grund, warum man die Gegenwart verwenden möchte, aber nur mit dem richtigen Projektstil. Bei dieser Denkweise werden alle Commits als optionale Verbesserungen oder Funktionen betrachtet, und Sie können frei entscheiden, welche Commits in Ihrem speziellen Repository beibehalten und welche abgelehnt werden sollen.

Dieses Argument funktioniert, wenn Sie es mit einem wirklich verteilten Projekt zu tun haben. Wenn Sie mit einem verteilten Projekt arbeiten, arbeiten Sie wahrscheinlich an einem Open Source-Projekt. Und es ist wahrscheinlich ein sehr großes Projekt, wenn es wirklich verteilt ist. In der Tat ist es wahrscheinlich entweder der Linux-Kernel oder Git. Da Linux wahrscheinlich dazu geführt hat, dass sich Git verbreitet und immer beliebter wird, ist es leicht zu verstehen, warum die Leute seinen Stil als Autorität betrachten. Ja, der Stil macht bei diesen beiden Projekten Sinn. Im Allgemeinen funktioniert es auch mit großen, verteilten Open Source- Projekten.

Allerdings funktionieren die meisten Projekte in der Quellcodeverwaltung nicht so. Dies ist normalerweise für die meisten Repositorys falsch. Es ist eine moderne Art, über Commits nachzudenken: Subversion- (SVN) und CVS-Repositorys könnten diese Art von Repository-Check-Ins kaum unterstützen. Normalerweise handhabte ein Integrationszweig das Filtern fehlerhafter Check-Ins, aber diese wurden im Allgemeinen nicht als "optional" oder "schön zu haben" angesehen.

In den meisten Szenarien schreiben Sie beim Festschreiben eines Quell-Repositorys einen Journaleintrag, in dem beschrieben wird, was sich mit diesem Update geändert hat, damit andere in Zukunft leichter verstehen können, warum eine Änderung vorgenommen wurde. Dies ist im Allgemeinen keine optionale Änderung. Andere Personen im Projekt müssen sie entweder zusammenführen oder neu erstellen. Sie schreiben keinen Tagebucheintrag wie "Liebes Tagebuch, heute treffe ich einen Jungen und er sagt Hallo zu mir.", Sondern Sie schreiben "Ich habe einen Jungen getroffen und er hat Hallo zu mir gesagt ."

Bei solchen nicht verteilten Projekten ist 99,99% der Zeit, in der eine Person eine Commit-Nachricht liest, für das Lesen des Verlaufs bestimmt - der Verlauf wird in der Vergangenheitsform gelesen. In 0,01% der Fälle wird entschieden, ob sie dieses Commit anwenden oder in ihre Zweigstelle / ihr Repository integrieren sollen.

  • Konsistenz. So ist es in vielen Projekten (einschließlich Git selbst). Auch Git-Tools, die Commits generieren (wie Git Merge oder Git Revert), tun dies.

Nein, ich garantiere Ihnen, dass die meisten Projekte, die jemals in einem Versionskontrollsystem angemeldet waren, ihren Verlauf in der Vergangenheitsform hatten (ich habe keine Referenzen, aber es ist wahrscheinlich richtig, wenn man bedenkt, dass das Argument der Gegenwartsform seit Git neu ist). "Revisions" -Nachrichten oder Commit-Nachrichten in der Gegenwart haben erst in wirklich verteilten Projekten Sinn gemacht - siehe den ersten Punkt oben.

  • Die Leute lesen nicht nur die Geschichte, um zu wissen, "was mit dieser Codebasis passiert ist", sondern auch um Fragen zu beantworten, wie "was passiert, wenn ich dieses Commit auswähle" oder "welche neuen Dinge aufgrund dieser Commits mit meiner Codebasis passieren werden." Ich kann oder kann nicht in der Zukunft verschmelzen ".

Siehe den ersten Punkt. 99,99% der Zeit, in der eine Person eine Commit-Nachricht liest, dient zum Lesen des Verlaufs - der Verlauf wird in der Vergangenheitsform gelesen. In 0,01% der Fälle wird entschieden, ob sie dieses Commit anwenden oder in ihre Zweigstelle / ihr Repository integrieren sollen. 99,99% schlagen 0,01%.

  • Es ist normalerweise kürzer

Ich habe noch nie ein gutes Argument gesehen, das besagt, dass man falsche Zeitform / Grammatik verwendet, weil es kürzer ist. Sie werden wahrscheinlich nur durchschnittlich 3 Zeichen für eine Standardnachricht mit 50 Zeichen speichern. Davon abgesehen wird die Gegenwart im Durchschnitt wahrscheinlich einige Zeichen kürzer sein.

  • Sie können Commits konsistenter mit Titeln von Tickets in Ihrem Issue- / Feature-Tracker benennen (die keine Vergangenheitsform verwenden, obwohl manchmal auch zukünftige)

Tickets werden entweder als etwas geschrieben , das derzeit geschieht (zB die App zeigt das falsche Verhalten , wenn ich auf diese Schaltfläche klicken), oder etwas , dass der Bedarf in der Zukunft durchgeführt werden (zB der Text muss eine Überprüfung durch die Redaktion).

Geschichte (dh Commit - Nachrichten) als etwas geschrieben , das in der Vergangenheit getan wurde (zB das Problem wurde festgelegt).

Matt Quigley
quelle
79
Ich habe heute zum ersten Mal von der angeblichen Präferenz für imperative Stilverpflichtungen gehört. Für mich klang es so unnatürlich und bizarr, dass ich mich entschied, weitere Meinungen einzuholen. Ich freue mich zu sehen, dass ich nicht der einzige bin, der der Meinung ist, dass Vergangenheitsform für Commit-Nachrichten natürlicher ist. :)
Karadoc
57
Die automatisch generierten Merge- und Rebase-Commit-Nachrichten von git sind zwingend erforderlich und in der Gegenwart ("Merge", nicht "Merged"; "Rebase", nicht "Rebased"). Daher sollten Sie dies aus Gründen der Konsistenz in Ihren eigenen Commit-Nachrichten abgleichen.
mjs
13
Es scheint, dass der Unterschied zwischen einem Fokus auf die Änderung der Software - "X durch Y behoben" - oder dem Repository - "Y tun, um X zu reparieren" liegt. +1 für ein gutes Argument, aber ich denke, das Repo sollte sich normalerweise auf sich selbst konzentrieren und nicht auf die resultierende Software.
10b0
28
Die Sache ist, imperative, Präsens-Werke für große Projekte (z. B. Linux) zu verwenden, damit sie offensichtlich skalieren. Darüber hinaus erfordert es so gut wie keine Anstrengung, die Vergangenheitsform zu verwenden. Infolgedessen sehe ich keinen Grund (außer "alte Leute werden verwendet, um Commit-Nachrichten in der Vergangenheitsform zu schreiben"), etwas anderes als die imperative Gegenwartsform zu verwenden. Wenn Sie den Befehlssatz git lernen können, können Sie das Schreiben in der Imperativ-Gegenwart lernen.
Mikko Rantalainen
35
Imperativ ist nicht "neu seit git". ChangeLog existierte lange vor Git, und die Verwendung von Imperativ war immer der empfohlene Stil im GNU-Projekt. gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
adl
81

Ich habe eine ausführlichere Beschreibung zu 365git geschrieben .

Die Verwendung der imperativen Gegenwart ist etwas gewöhnungsbedürftig. Als ich anfing, es zu erwähnen, stieß es auf Widerstand. Normalerweise im Sinne von "Die Festschreibungsnachricht zeichnet auf, was ich getan habe". Git ist jedoch ein verteiltes Versionskontrollsystem, bei dem es möglicherweise viele Orte gibt, an denen Änderungen vorgenommen werden können. Anstatt Nachrichten zu schreiben, die sagen, was Sie getan haben; Betrachten Sie diese Nachrichten als Anweisungen für die Anwendung des Commits. Anstatt ein Commit mit dem Titel zu haben:

Renamed the iVars and removed the common prefix.

Haben Sie eine davon:

Rename the iVars to remove the common prefix

Was jemandem sagt, was das Anwenden des Commits bewirken wird, anstatt was Sie getan haben. Wenn Sie sich Ihren Repository-Verlauf ansehen, werden Sie feststellen, dass die von Git generierten Nachrichten auch in dieser Zeitform geschrieben sind - "Zusammenführen", nicht "Zusammengeführt", "Rebase", nicht "Rebased", sodass das Schreiben in derselben Zeitform konsistent bleibt. Es fühlt sich zunächst seltsam an, macht aber Sinn (Testimonials auf Anfrage erhältlich) und wird schließlich natürlich.

Abgesehen davon - es ist Ihr Code, Ihr Repository: Richten Sie also Ihre eigenen Richtlinien ein und halten Sie sich an diese.

Wenn Sie sich jedoch für diesen Weg entscheiden, ist git rebase -ies eine gute Sache, die Umformulierungsoption zu prüfen.

Abizern
quelle
7
Nun, Sie haben zwei verschiedene Richtlinien verwechselt: das Git-Open-Source-Projekt und die regelmäßige Verwendung von Git. Der bereitgestellte Link erwähnt überhaupt keine Zeitform . Das offizielle Git-Dokument erwähnt nur das 50-Zeichen-Limit. Git ist ein verteiltes VCS, in dem es viele Stellen gibt, an denen Änderungen vorgenommen werden können. Betrachten Sie diese Nachrichten als Anweisungen für die Anwendung des Commits. Dies gilt nur für wenige Projekte, bei denen es sich tatsächlich um verteilte Projekte handelt. 99,999% der Git-Commits werden niemals manuell auf diese Weise angewendet. In den meisten Projekten ist der Verlauf ein Änderungsprotokoll, das sich in der Vergangenheitsform befinden sollte.
Matt Quigley
4
"und sollte den
Punkt
30

Halten Sie sich an den Präsens-Imperativ, weil

  • Es ist gut, einen Standard zu haben
  • Es werden Tickets im Bug-Tracker abgeglichen, die natürlich die Form "etwas implementieren", "etwas reparieren" oder "etwas testen" haben.
Craig P. Motlin
quelle
16

Für wen schreibst du die Nachricht? Und liest dieser Leser normalerweise die Nachricht vor oder nach dem Besitz des Commits selbst?

Ich denke, hier wurden aus beiden Perspektiven gute Antworten gegeben. Ich würde vielleicht nicht behaupten, dass es für jedes Projekt die beste Antwort gibt. Die getrennte Abstimmung könnte dies nahe legen.

dh zusammenfassen:

  • Ist die Nachricht vorwiegend für andere Personen gedacht, die normalerweise irgendwann lesen, bevor sie die Änderung angenommen haben: Ein Vorschlag, wie sich die Änderung auf ihren vorhandenen Code auswirkt.

  • Ist die Nachricht vorwiegend als Tagebuch / Aufzeichnung für Sie selbst (oder für Ihr Team), aber in der Regel aus der Perspektive gelesen, die Änderung angenommen zu haben und zurück zu suchen, um herauszufinden, was passiert ist.

Vielleicht führt dies die Motivation für Ihr Team / Projekt in beide Richtungen.

wardw
quelle
10

ist es wichtig Leute sind im Allgemeinen klug genug, um Nachrichten richtig zu interpretieren. Wenn dies nicht der Fall ist, sollten Sie sie wahrscheinlich sowieso nicht auf Ihr Repository zugreifen lassen!

Michael Baldry
quelle
27
Für manche Menschen sind solche Dinge ziemlich wichtig.
Wesley Murch
2
@mog der Link macht keine Aussage über Gegenwart und Vergangenheit.
Ceving
2
Wenn das Projekt sehr umfangreich ist, werden die Leute, die Codeüberprüfung und Fehlersuche durchführen, so viele Commits sehen, dass sie alle Hilfe benötigen, die Sie und ich leisten können. Es macht keinen Sinn, jetzt ein paar Sekunden zu sparen, um in Zukunft große Kopfschmerzen zu verursachen, wenn keine ordnungsgemäße Festschreibungsnachricht geschrieben wird.
Mikko Rantalainen
Ich sage nicht, schreibe keine gute Commit-Nachricht. Ich sage, es spielt keine Rolle, ob Sie Vergangenheits- oder Gegenwartsform verwenden.
Michael Baldry
1
Wie würden Sie wissen, dass die Person, die Ihre Festschreibungsnachricht nicht interpretieren kann, die Ursache dafür ist, dass diese Person nicht in der Lage oder nicht in der Lage ist, eine gute Festschreibungsnachricht zu schreiben?
Haris
7

Es liegt an dir. Verwenden Sie einfach die Commit-Nachricht, wie Sie möchten. Es ist jedoch einfacher, wenn Sie nicht zwischen Zeiten und Sprachen wechseln.

Und wenn Sie sich in einem Team entwickeln, sollte dies besprochen und festgelegt werden.

Andreas Rehm
quelle