{"id":810,"date":"2011-12-11T16:43:21","date_gmt":"2011-12-11T15:43:21","guid":{"rendered":"https:\/\/sgaul.de\/?p=810"},"modified":"2011-12-11T16:43:21","modified_gmt":"2011-12-11T15:43:21","slug":"commit-messages-im-vergleich","status":"publish","type":"post","link":"https:\/\/sgaul.de\/2011\/12\/11\/commit-messages-im-vergleich\/","title":{"rendered":"Commit-Messages im Vergleich"},"content":{"rendered":"

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\u00f6nnen, was die \u00c4nderung 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.<\/p>\n

Linus Torvalds und die Commit-Message-Struktur<\/h2>\n

Contributing:<\/p>\n

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
\nthem. 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
\nthe right to pass it on as an open source patch.<\/p>\n

See: http:\/\/gerrit.googlecode.com\/svn\/documentation\/2.0\/user-signedoffby.html<\/p>\n

Also, please write good git commit messages. A good commit message looks like this:<\/p>\n

Header line: explaining the commit in one line<\/p>\n

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.<\/p>\n

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.<\/p>\n

Reported-by: whoever-reported-it
\nSigned-off-by: Your Name<\/code><\/p>\n

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
\nshortlog, and should summarize the change in one readable line of text, independently of the longer explanation.<\/p>\n

Quelle: Subsurface-Readme-Datei auf Github<\/a><\/p>\n<\/blockquote>\n

Neben einer knappen Header-Zeile erwartet Herr Torvalds also noch einen ausf\u00fchrlichen K\u00f6rper, der Details und Hintergr\u00fcnde erl\u00e4utert. Ein besonders interessantes Detail ist die letzte Zeile: Mit \u201eSigned-off-by\u201c b\u00fcrgt der Beitragende daf\u00fcr, dass er das Recht hat, den \u00fcbermittelten Code zu den Bedingungen des Projekts bereitzustellen.<\/p>\n

Linux: Aus der Sicht der \u00c4nderung<\/h2>\n

Im Linux-Projekt findet man viele Meldungen wie diese:<\/p>\n

\nARM: davinci: psc: fix incorrect offsets<\/code><\/p>\n

Quelle: https:\/\/github.com\/torvalds\/linux\/commits\/master?page=4<\/a><\/p>\n<\/blockquote>\n

Hier wird zun\u00e4chst eingeschr\u00e4nkt, auf welche Bereiche sich die \u00c4nderung bezieht. Die Meldung selbst ist im Pr\u00e4sens und aus Sicht des Commits formuliert. Als Hilfestellung f\u00fcr eine konsequente Umsetzung k\u00f6nnte etwa folgender Einstieg helfen: \u201eIch bin eine \u00c4nderung und…\u201c F\u00fcr obiges Beispiel w\u00e4re das: \u201eIch bin eine \u00c4nderung und behebe falsche Offsets.\u201c<\/p>\n

Doch auch das Vorzeigeprojekt ist nicht immer konsequent.<\/p>\n

\nARM: davinci: dm646x does not have a DSP domain<\/code><\/p>\n

Quelle: https:\/\/github.com\/torvalds\/linux\/commit\/9ab409e402cbfde11e2516be43921954db480f4d<\/a><\/p>\n<\/blockquote>\n

Hier wird anstelle der \u00c4nderung ein Problem beschrieben. Dies f\u00fchrt unweigerlich zu Konsistenzproblemen: F\u00fcge ich ein Feature hinzu, kann ich keine gleichartige Meldung konstruieren.<\/p>\n

WordPress: Keine Module, mehr Menschlichkeit<\/h2>\n

WordPress h\u00e4lt es mit den Commit-Messages recht \u00e4hnlich:<\/p>\n

\nFix list styling. Props koopersmith, azaozz, trepmal. fixes #19453<\/code><\/p>\n

Quelle: WordPress-Repository<\/p>\n<\/blockquote>\n

Auch hier bestimmt die aktive Pr\u00e4sensform das Bild. Allerdings neigen die WordPress-Entwickler zu mehrs\u00e4tzigen Headern, die offensichtlich sogar Danksagungen enthalten k\u00f6nnen. 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\u00fcht (\u201ethe commit fixes<\/em>…\u201c).<\/p>\n

Gnome: Die Entwicklersicht<\/h2>\n

Bei Gnome beschreiben die meisten Entwickler, was sie taten<\/em>, als sie die \u00c4nderung machten. Dementsprechend wird auch in der Vergangenheitsform geschrieben:<\/p>\n

\nUpdated on-screen-keyboard patches (squashed)<\/code><\/p>\n

Quelle: http:\/\/git.gnome.org\/browse\/gnome-shell\/commit\/?h=osk<\/a><\/p>\n<\/blockquote>\n

Guideline f\u00fcr Commit-Messages<\/h2>\n

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\u00e4sst sich mit wenigen Fragen fixieren:<\/p>\n

    \n
  1. Modularisierung durch z.B. \u201eModul:\u201c am Anfang des Message-Headers?<\/li>\n
  2. \u00c4nderungs- oder Entwicklersicht (Pr\u00e4sens oder Pr\u00e4teritum)? \u201eFix…\u201c oder \u201eFixed…\u201c?<\/li>\n
  3. Aus Sicht der ersten oder dritten Person? \u201eFix…\u201c oder \u201eFixes…\u201c?<\/li>\n
  4. Trennzeichen im Header? \u201eFix a; add b\u201c oder \u201eFix a. Add b.\u201c?<\/li>\n
  5. Gro\u00df- und Kleinschreibung oder konsequente Kleinschreibung?<\/li>\n
  6. Zus\u00e4tzliche Angaben wie Issue-Nummern?<\/li>\n<\/ol>\n

    Kl\u00e4rt man diese Punkte am Anfang des Projektes, erh\u00e4lt man einen sch\u00f6nen Changelog, den man auch auf einer Internetseite pr\u00e4sentieren kann.<\/p>\n","protected":false},"excerpt":{"rendered":"

    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\u00f6nnen, was die \u00c4nderung 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.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[91],"tags":[266,269,270],"_links":{"self":[{"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/posts\/810"}],"collection":[{"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/comments?post=810"}],"version-history":[{"count":25,"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/posts\/810\/revisions"}],"predecessor-version":[{"id":836,"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/posts\/810\/revisions\/836"}],"wp:attachment":[{"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/media?parent=810"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/categories?post=810"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sgaul.de\/wp-json\/wp\/v2\/tags?post=810"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}