git Commit Guideline

Tagged Frontend Entwicklung Git commit guidline by planungsbüro INTERNET

Um einen Überblick der Änderungen innerhalb eines Projekts zu behalten und arbeiten zu können, ohne das Gefühl haben zu müssen, dass Änderungen verloren gehen könnten, verwenden wir das Versionskontrollsystem git. Je mehr Leute an einem Projekt mitarbeiten, desto vielseitiger fallen allerdings auch die sogenannten Commit-Messages im git-System aus. Eine solche Message muss immer dann verfasst werden, wenn ein Teammitglied Änderungen in einem Projekt gemacht hat, und diese dem restlichen Team zugänglich machen möchte. Es ist schwierig, auf einen Blick zu verstehen, was in einem Commit geändert wurde, wenn Commit-Messages unterschiedlichen Strukturen folgen, oder auch gar keiner.
Commit-Messages wie fixes, spacing, lots of work on the header oder added new button sind viel zu unspezifisch und sagen leider nicht aus, was an welcher Stelle verändert wurde.

Es liegt nahe, sich auf eine gemeinsame Strategie zu einigen, wie Commit-Messages formuliert werden sollten. Dadurch wird es für alle Beteiligten einfacher, Änderungen im Code anhand der Commit-Message genau nachvollziehen zu können.

Verschiedene Open-Source-Projekte haben zu diesem Zweck bereits umfangreiche Dokumentationen erstellt, wie Beteiligte ihre Änderungen beschreiben sollen. Beispiele für solche Guidelines kommen zum Beispiel von AngularJS oder jQuery.

Im AngularJS-Projekt werden behobene Fehler mit fix(module): description dokumentiert. Man erkennt sofort, dass es sich um einen Bugfix im Modul module handelt. Neue Funktionen werden mit feat(module): description gekennzeichnet. Generell folgt jede Commit Message dieser Struktur <type>(<scope>): <subject>. Für verschiedene Tätigkeiten am Code gibt es verschiedene Typen, wie die bereits aufgeführten fix und feature und weitere wie docs für Änderungen an der Dokumentation oder refactor für Refactorings (Verbesserung des Codes ohne etwas an seiner Funktion zu verändern).

Dadurch ist es möglich, wichtige Änderungen am Projekt direkt im git-Log zu erkennen und eher unwichtige Commits auszufiltern.

Changelog automatisch aus dem git-Log generieren

Neben der Übersichtlichkeit ergibt sich aus dieser Konvention ein weiterer Vorteil: die Commit-Messages können bei der Veröffentlichung einer neuen Projekt-Version dazu verwendet werden, automatisiert einen Changelog mit allen Änderungen seit dem letzten Release zu erstellen.

Das Node.js-Package conventional-changelog durchsucht zum Beispiel alle Commits seit dem letzten Release und schreibt bestimmte Commit-Typen (zum Beispiel nur Features und Bugfixes) in den Changelog und gruppiert sie nach ihrem scope (Beispiel: AngularJS-Changelog). Außen vor bleiben “housekeeping” Commits, wie Änderungen der Dokumentation oder Formatierungen.

Commit-Messages à la Planungsbüro

In unseren Projekten verwenden wir eine ähnliche Konvention für Commit-Messages. Der grundsätzliche Aufbau folgt dabei dem AngularJS-Beispiel:

<type>(<scope>): <subject>

<description>

Fixes #aaa
Ref #aaa

Types

Wir setzen folgende Typenschilder für alle unsere Änderungen ein:

  • feat – Feature: Erweitert ein Modul um eine neue Funktion oder erstellt ein neues Modul.
  • enh – Enhancement: Ändert ein Modul. Zum Beispiel optische Anpassungen im CSS.
  • fix – Fix: Behebt einen Fehler.
  • wip – Work in Progress: Markiert unfertigen Code. Grundsätzlich sollte so ein Commit vermieden werden.
  • con – Content: Ändert oder erweitert Inhalte, zum Beispiel Text auf einer Webseite.
  • docs – Documentation: Betrifft die Dokumentation.
  • refactor – Refactoring: Umbau von Code, ohne das Verhalten der Funktion zu ändern.
  • style – Style: Betrifft Formatierungen oder Whitespace. Keine technische Änderung am Code.
  • chore – Chore: Kennzeichnet Änderungen am Build-Prozess, oder den Release neuer Versionen.

Die in bold hervorgehobenen Typen werden in unserer Konfiguration von conventional-changelog automatisch in den Changelog übernommen.

Scope

Diese Angabe macht klar, welches Modul der Commit geändert hat. Zum Beispiel nur den teaser oder die navigation. Betrifft die Änderung das gesamte Projekt, kann der Scope auch entfallen.

Wir modularisieren unsere Proejekte soweit es geht. Das spiegelt sich auch in unserer CSS-Naming-Guideline wieder. Ein CSS-Modul oder Komponenten eignen sich gut als Modul-Name in der Commit-Message.

Subject

Der Betreff ist eine kurze, prägnante Zusammenfassung des Commits mit folgenden Vorschriften:.

  • Keine Großschreibung am Beginn.
  • Kein Punkt am Ende.
  • Wird auf Englisch verfasst.
  • Die Verbindung aus type, scope und subject sollte idealerweise um die 50 Zeichen lang sein, aber auf keinen Fall 72 Zeichen überschreiten. [1]
  • Im Präsens formulieren: add styling for last item anstelle von added styling for last item

Description

Eine optionale, ausführlichere Erklärung des Commits. Hier geben wir vor allem an, ob sich ein Commit auf ein Ticket aus unserem Ticket-System bezieht.

  • Eine Zeile sollte nicht länger als 72 Zeichen sein. [1]
  • Schließt der Commit ein Ticket, wird dies mit Fixes #1234 vermerkt.
  • Behandelt der Commit ein Ticket, schließt es aber nicht, wird das Ticket mit Ref #1234 referenziert.
  • Tangiert der Commit mehrere Tickets werden die Ticket-Nummern kommasepariert nacheinander angeführt Ref #1234, #5678.

Beispiele für gute Commit-Messages

Einige Beispiele wie gute Commit-Messages aussehen könnten:

feat: add icon font
feat(imageteaser): inital commit
fix(mainnav): add aria-haspopup for Windows Mobile dropdowns
enh(header): more inner spacing
chore(grunt): add SVG icon sprite task
chore: release v0.1.23
style(tools): format according to .editorconfig
con(index): set teaser row

  1. http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html  ↩