Commit-Messages im Vergleich

Oft ist ein Fehler schnell behoben, doch der Teufel steckt im Detail: Wie beschreibt man nun, was man gerade getan hat? Wie fasst man seine Gedanken in eine Commit-Message, so dass andere Entwickler auch wirklich nachvollziehen können, was die Änderung macht? Welche Zeitform nutzt man, welche Perspektive und Struktur? Ein kleiner Blick auf die Welt der freien Software und die kleinen Nachrichten, die sie zusammenhalten.

Linus Torvalds und die Commit-Message-Struktur

Contributing:

Please either send me signed-off patches or a pull request with signed-off commits. If you don’t sign off on them, I will not accept
them. This means adding a line that says „Signed-off-by: Name“ at the end of each commit, indicating that you wrote the code and have
the right to pass it on as an open source patch.

See: http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html

Also, please write good git commit messages. A good commit message looks like this:

Header line: explaining the commit in one line

Body of commit message is a few lines of text, explaining things in more detail, possibly giving some background about the issue being fixed, etc etc.

The body of the commit message can be several paragraphs, and please do proper word-wrap and keep columns shorter than about 74 characters or so. That way "git log" will show things nicely even when it's indented.

Reported-by: whoever-reported-it
Signed-off-by: Your Name

where that header line really should be meaningful, and really should be just one line. That header line is what is shown by tools like gitk and
shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.

Quelle: Subsurface-Readme-Datei auf Github

Neben einer knappen Header-Zeile erwartet Herr Torvalds also noch einen ausführlichen Körper, der Details und Hintergründe erläutert. Ein besonders interessantes Detail ist die letzte Zeile: Mit „Signed-off-by“ bürgt der Beitragende dafür, dass er das Recht hat, den übermittelten Code zu den Bedingungen des Projekts bereitzustellen.

Linux: Aus der Sicht der Änderung

Im Linux-Projekt findet man viele Meldungen wie diese:

ARM: davinci: psc: fix incorrect offsets

Quelle: https://github.com/torvalds/linux/commits/master?page=4

Hier wird zunächst eingeschränkt, auf welche Bereiche sich die Änderung bezieht. Die Meldung selbst ist im Präsens und aus Sicht des Commits formuliert. Als Hilfestellung für eine konsequente Umsetzung könnte etwa folgender Einstieg helfen: „Ich bin eine Änderung und…“ Für obiges Beispiel wäre das: „Ich bin eine Änderung und behebe falsche Offsets.“

Doch auch das Vorzeigeprojekt ist nicht immer konsequent.

ARM: davinci: dm646x does not have a DSP domain

Quelle: https://github.com/torvalds/linux/commit/9ab409e402cbfde11e2516be43921954db480f4d

Hier wird anstelle der Änderung ein Problem beschrieben. Dies führt unweigerlich zu Konsistenzproblemen: Füge ich ein Feature hinzu, kann ich keine gleichartige Meldung konstruieren.

WordPress: Keine Module, mehr Menschlichkeit

WordPress hält es mit den Commit-Messages recht ähnlich:

Fix list styling. Props koopersmith, azaozz, trepmal. fixes #19453

Quelle: WordPress-Repository

Auch hier bestimmt die aktive Präsensform das Bild. Allerdings neigen die WordPress-Entwickler zu mehrsätzigen Headern, die offensichtlich sogar Danksagungen enthalten können. Auch das behobene Problem wird direkt mit seiner Nummer benannt, was z.B. Track benutzt, um den entsprechenden Issue direkt als behoben zu markieren. Hier wird allerdings die Sicht einer dritten Person bemüht („the commit fixes…“).

Gnome: Die Entwicklersicht

Bei Gnome beschreiben die meisten Entwickler, was sie taten, als sie die Änderung machten. Dementsprechend wird auch in der Vergangenheitsform geschrieben:

Updated on-screen-keyboard patches (squashed)

Quelle: http://git.gnome.org/browse/gnome-shell/commit/?h=osk

Guideline für Commit-Messages

Die meisten anderen Projekte fallen in eine der oben genannten Kategorien. Dies ist auch nicht verwunderlich, schlussendlich gibt es nur begrenzt viele sinnvolle Varianten. Die Form der Commit-Message lässt sich mit wenigen Fragen fixieren:

1. Modularisierung durch z.B. „Modul:“ am Anfang des Message-Headers?
2. Änderungs- oder Entwicklersicht (Präsens oder Präteritum)? „Fix…“ oder „Fixed…“?
3. Aus Sicht der ersten oder dritten Person? „Fix…“ oder „Fixes…“?
4. Trennzeichen im Header? „Fix a; add b“ oder „Fix a. Add b.“?
5. Groß- und Kleinschreibung oder konsequente Kleinschreibung?
6. Zusätzliche Angaben wie Issue-Nummern?

Klärt man diese Punkte am Anfang des Projektes, erhält man einen schönen Changelog, den man auch auf einer Internetseite präsentieren kann.