Klartext für Git und Co.

Best Practices: Das Formulieren aussagekräftiger Commit Messages
Keine Kommentare

Source Control Management Systems (SCM) gehören für Entwickler zum Standardrepertoire. Aus dem breiten Angebot der Tools ist Git eine der beliebtesten Lösungen. Obwohl viele Nutzer mit den weiterführenden Konzepten im Umgang mit SCMWerkzeugen geübt sind, wird die Möglichkeit zu jedem Commit eine Beschreibung zu hinterlegen etwas vernachlässigt. Das Formulieren aussagekräftiger Commit Messages kann in vielen Situationen die Produktivität im Entwicklungsteam verbessern.

Die Erkenntnis, dass Commit Messages von Bedeutung sind, haben einige Technologieblogs (chris.beams.io, who-t.blogspot.mx, slideshare.net) im Internet bereits sehr anschaulich ausgeführt. Die dort beschriebenen Erfahrung haben die Meisten mittlerweile selbst gesammelt. Viele Unternehmen haben auf diesen Umstand reagiert und formulierten Style Guides für das Verfassen von Commit Messages. Beim Durchstöbern der Repositorien des Cloud-Sourcecodehosters GitHub ist eine deutliche Verbesserung der gesamten Situation zu erkennen.

Trotz der vielen und sehr wertvollen Ratschläge gibt es einiges an Optimierungsmöglichkeiten. Eine wesentliche Überlegung ist die Tatsache, dass man als Entwickler seinen Fokus auf das Umsetzen der geforderten Funktionalität gerichtet hat und weniger auf die ebenso wichtige Dokumentation. Das Problem ergibt sich daraus, dass man sehr stark in die Thematik vertieft ist und viele der Details, die für Außenstehende wertvoll sind, als zu trivial bewertet. Dieser Umstand erschwert es, einen geeigneten Kommentar zu verfassen.

Best Practices für Git und Co.

Es finden sich häufig kommentierte Revisionen mit der Beschreibung „Anpassen der Build-Logik“. Das gibt aber keinen Aufschluss darüber, um was für eine Anpassung es sich handelt. Wurde die Versionsnummer für ein Release verändert oder wurde eine neue Abhängigkeit zu einer Bibliothek hinzugefügt? Oder wurde die aktuelle Version eines Artefakts wie JUnit angepasst und musste gegebenenfalls diese Anpassung wegen Inkompatibilitäten zurückgezogen werden? Alle diese Informationen bieten einen enormen Mehrwert in der Projektarbeit, ohne dass E-Mail-Postfächer verstopft werden. Jeder Entwickler erkennt mit einem Blick in die Revision History des SCM-Systems den aktuellen Status des Projektes.

Um diese Situation zu entlasten, hat der Autor eine Methode entwickelt, die es dem Nutzer durch ein vordefiniertes Vokabular ermöglicht, seine Arbeit leichter zu reflektieren und sein Ergebnis so ausdrucksstark formulieren zu können. Die erarbeiteten Ausdrücke orientieren sich vollständig am üblichen Sprachgebrauch in Softwareentwicklungsprojekten. Die hier beschriebene Methodik eignet sich übrigens auch für andere Bereiche der Softwareentwicklung. Die vorgestellten sprachlichen Mittel können ebenso in agilen Teambesprechungen angewendet werden. Speziell in zeitlich limitierten Treffen wie beim Daily Scrum kann das die Kommunikation verbessern.

Fünf Strukturelemente

Wie bereits erwähnt, handelt es sich bei der vorgestellten Methode um eine Sprache mit einem sehr begrenzten Wortschatz. Für die Notation wurden die Standards der Softwareentwicklung berücksichtigt. Wichtigste Bezugselemente sind der Releaseprozess und das Semantic Versioning. Um künftig eine maschinelle Auswertung ermöglichen zu können, ist ein Kommentar in fünf Bereiche untergliedert: FuctionID, Labels, Specification, TaskID und Comment. Diese fünf Elemente unterliegen einer festen Notation, die in Abbildung 1 grafisch dargestellt ist.

Abb. 1: Strukturelemente

Abb. 1: Strukturelemente

Die erste Zeile besteht aus einem Identifier, der eine Funktions-ID repräsentiert. An zweiter Stelle kennzeichnet ein Label den zugehörigen Kontext, der in der dritten Position spezifiziert wird. Die zweite Zeile mit der Referenz zur Task-ID aus dem Issue Management, sowie die dritte Zeile mit einem ausführlichem Kommentar sind optional. Die Wahl einer Funktions-ID, anstatt einer Task- bzw. einer Issue-ID begründet sich aus verschiedenen Überlegungen. Zum einem soll die hier vorgestellte Lösung möglichst flexibel für allerlei Projekte gehalten werden. So wird man der Tatsache gerecht, dass es Projekte geben kann, die mit keinem Issue-Management-System verknüpft sind.

Kostenlos: IPC Agile Cosmos Cheat Sheet

Agile Cosmos Cheat Sheet-small-220x311In diesem Cheat-Sheet von unserem Experten René Schröder bekommen Sie einen Überblick über den Agile Cosmos und die organisatorische Struktur. Mit diesem Mind-Map haben Sie die perfekte Voraussetzung, um entweder Ihr eigenes agiles Team aufzubauen, Ihre aktuelle Organisation zu verbessern oder einen eigenen Stil von Agil zu kreieren.

Ein weiterer Aspekt ist dem Umstand geschuldet, dass es vielfach vorkommt, dass Funktionalitäten über mehrere Tasks verteilt sind. Schneidet man allerdings die Anwendung nach deren Funktionen, wie es beispielsweise bei dem Projekt TP-CORE auf GitHub der Fall ist, können sämtliche Revisionen der entsprechenden Funktionalität zugeordnet werden. Das erlaubt eine neue Betrachtungsweise durch Metriken. Mit einer Suche über die Funktions-ID lassen sich sämtliche Revisionen innerhalb eines Releases feststellen, die Hinweise zu tatsächlichen Aufwänden geben. Durch Labels wie Bugfix oder Implement kann der Evolutionsprozess des gesamten Artefakts genauer eingeschätzt werden. Die darauffolgende Spezifikation fokussiert die Details. In der nachfolgenden Übersicht wird ein Basisvokabular für Labels und deren zugehörige Spezifikation definiert.

Das Vokabular kann natürlich bei Bedarf an eigene Anforderungen weiter angepasst werden. Adaptionen sollten der Übersicht wegen sehr genau abgewogen werden und nur dann eingeführt werden, wenn mit den vorhandenen Mitteln der Prozess nicht beschrieben werden kann. Werden bestehende Strukturen erweitert, kann das künftig den Einsatz von zusätzlicher Standardsoftware erschweren, da hier ebenfalls Anpassungen vorzunehmen sind, wenn Abweichungen bestehender Konventionen vorhanden sind.

  • #INIT – Initialisiert ein Repository oder ein neues Release
    • repro:documentation / configuration …
    • archetype:jar / war / ear / pom / zip …
    • version:version
  • #IMPLEMENT – Implementieren einer neuen Funktion
    • function:clazz
  • #CHANGE – Ändern einer bestehenden Funktion
    • function:clazz
  • #EXTEND – Erweitern einer vorhandenen Funktion
    • function:clazz
    • attach:clazz
  • #BUGFIX – Fehlerkorrektur
    • priority:critical / medium / low / design
  • #REVIEW – Qualitätssicherung
    • refactor:function
    • analyze:quality
    • migrate:function
    • format:source
  • #RELEASE – Fertigstellung eines Artefaktes zur Auslieferung
    • version:version
  • #REVERT – Rücknahme einer Revision
    • commit:id
  • #BRANCH – Erzeugen einer Verweigung
    • create:name
    • stash:branch
  • #MERGE – Zusammenführen einer Verzweigung
    • from:branch
    • to:branch
  • #CLOSE – Schließen eines Entwicklungszweiges
    • branch:name

Auch wenn das vorgestellte Konzept leicht anzuwenden ist, soll an dieser Stelle ein einfaches Beispiel einer Commit Message die Zusammenhänge skizzieren.

[CORE-02] #IMPLEMENT ’function:GenericDAO’
<Core_0021526>
{Generic Data Access Object Pattern for centralized database access.}

Die hier dargestellte Commit Message besagt, dass die Funktion GenericDAO, welche der Funktions-ID CORE-02 zugeordnet ist, implementiert wurde. Der zugehörige JIRA-Task lautet: Core_0021526.

Best Practice für Länge und Thematik

Auch wenn die Länge der Commit Messages nicht limitiert ist, ist es empfehlenswert, die Zeichenlänge der ersten Zeile auf 80 bis 100 zu begrenzen. Lässt man sich beispielsweise die History in einem Client wie Tortoise-Git oder SmartGit anzeigen, wird die erste Zeile in der Übersicht dargestellt. Ist die darin enthaltene Nachricht zu lang, muss sie abgeschnitten werden und der Vorteil einer kompakten Darstellung wurde somit verschenkt (Abb. 2).

Abb. 2: TortoiseGit History

Abb. 2: TortoiseGit History

Ein anderer Punkt ist die Thematik, dass nicht alle Aktivitäten, die Änderungen im Code-Repository erfordern, einer speziellen Funktion zugeordnet werden können. Anpassungen der Build-Logik sind beispielsweise solche Tätigkeiten. Für diese Fälle können projektübergreifende Funktions-IDs angelegt werden. Beispiele sind:

  • [CM-000] INIT – Erzeugen oder Initialisieren eines Repositorys
  • [CM-010] REVIEW – Projektübergreifende Qualitätsanpassungen durch ein Architekturboard
  • [CM-020] BRANCH – SCM-Aktivität
  • [CM-030] MERGE – SCM-Aktivität
  • [CM-040] RELEASE – Anpassen der Build-Nummer eines Artefakts für ein Release
  • [CM-050] build management – Hinzufügen von weiteren Bibliotheken

Das Kürzel CM steht hier für Konfigurationsmanagement. Die Tätigkeiten {INIT, REVIEW, etc.} stellen in diesem Fall die Funktionsbeschreibung dar und kein Label. Ein typisches Beispiel einer solchen administrativen Tätigkeit ist das Initialisieren des Code-Repository.

[CM-000] #INIT ’archtype:jar’
{Initial the repository for Java JAR library.}

Um ein Gefühl für die Mächtigkeit des hier vorgestellten Konzepts zu entwickeln, sollten Sie einen Blick in den Kasten „Beispielprojekt mit verschiedenen Revisionen“ werfen. Diesem Beispiel liegt die auf GitHub publizierte Bibliothek TP-CORE zugrunde, die als Java-Artefakt auf Maven Central deployt und releast wurde.

Fazit

Wie gezeigt werden konnte, ist die Verwendung strukturierter Commit Messages sehr leicht in bestehende Prozesse einzubinden. Die daraus resultierenden Vorzüge sind vielfältig und eröffnen neue Möglichkeiten, Informationen aus Source-Control-Management-Systemen zu gewinnen. Die diesem Artikel zugrundeliegende wissenschaftliche Ausarbeitung steht frei verfügbar auf ResearchGate zum Download bereit. Der in englischer Sprache geschriebene Text gibt zusätzliche Anregungen, wie die Informationsgewinnung in SCM-Systemen weiter verbessert werden kann.

PHP Magazin

Entwickler MagazinDieser Artikel ist im PHP Magazin erschienen. Das PHP Magazin deckt ein breites Spektrum an Themen ab, die für die erfolgreiche Webentwicklung unerlässlich sind.

Natürlich können Sie das PHP Magazin über den entwickler.kiosk auch digital im Browser oder auf Ihren Android- und iOS-Devices lesen. In unserem Shop ist das Entwickler Magazin ferner im Abonnement oder als Einzelheft erhältlich.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu:
X
- Gib Deinen Standort ein -
- or -