Sinnvolle Git-Commit Messages für PCB-Designs, Layouts, Hardware-Entwicklung

16. Juni 2025

Tags: #git, #versionskontrolle, #best-practices, #hardware-entwicklung, #pcb-design, #layout

In der modernen, sprich: agilen Hardware-Entwicklung versionieren wir nicht mehr mit Nummern, sondern nutzen Git. Vielleicht macht ihr auch beides: git intern, mit Meilensteinen als Nummern für Kommunikation nach außen.

Wir schreiben mittlerweile auf Kupfer oder in den Bestückdruck unserer PCB-Designs / Layouts eine Kurzform des git-Hashs der verwendeten Version (statt wie früher unserer Versionsnummern, die wir durchnummerierten und mit Ziffern versahen, wie z.B. PCB2109D). Und wenn man an einer bestückten Leiterplatte / Elektronik arbeitet, für Inbetriebnahme von Prototypen, Testen von Funktionalitäten, Messen und Aufzeichnen von Werten, Kalibrieren von Sensoren, Bug Hunting und Bug Fixing, dann freuen wir uns, wenn wir genau wissen, welche Version wir vor uns haben und wie die Designdaten genau für diese Version aussehen. Und das hat früher mit den Versionsnummern nicht immer geklappt.

Git lässt sich automatisieren, weil auf Kommandozeile einsetzbar. Es fördert das kollaborative Arbeiten, mit seinen Branches fürs parallele Bearbeiten von Features, aber auch mit seinen einfachen Verteilmechanismen. Jedenfalls ist Git als Versionskontrollsystem in unserer Arbeit nicht mehr wegzudenken. Doch während das Tool selbst mittlerweile zum Standard gehört, wird die Qualität von Commit-Messages oft vernachlässigt. Dabei sind präzise und informative Commit-Nachrichten entscheidend für eine effiziente Teamarbeit und bessere Nachvollziehbarkeit der Projekthistorie.

Warum sind gute Commit-Messages wichtig?

Sinnvolle Git-Commit Messages haben in der Hardware-Entwicklung einen besonderen Stellenwert:

Nachvollziehbarkeit: Sie dokumentieren, warum Änderungen am PCB-Design vorgenommen wurden, nicht nur was geändert wurde
Effizienz: Bei der Fehlersuche können relevante Hardware-Änderungen schneller identifiziert werden
Wissensweitergabe: Neue Teammitglieder können die Entwicklungshistorie des Designs besser verstehen
Rückverfolgbarkeit: Jede Änderung lässt sich zu einem bestimmten Zeitpunkt und Grund zurückverfolgen

Bei alpha-board haben wir festgestellt, dass strukturierte Commit-Messages den Workflow erheblich verbessern und die Qualität unserer Arbeit erhöhen.

Die Struktur einer guten Commit-Message

Eine ideale Commit-Message folgt diesem Aufbau:

<typ>(<bereich>): <kurze zusammenfassung>

<detaillierte beschreibung>

<referenzen>

Hier unsere Tipps für den Inhalt einer guten Commit-Message.

1. Der Typ definiert die Art der Änderung

Conventional Commits basiert auf der Angular Commit Convention (2012). Google's Angular Team entwickelte diese Struktur, um:

Automatisches Changelog generieren zu können
Semantic Versioning zu automatisieren
Code-Reviews zu strukturieren

Es gibt viele mögliche Commit-Types, je nachdem, womit ihr euch beschäftigt. Für unsere Hardware-Entwicklungen haben sich diese hier bewährt:

feat: Neue Funktionalität oder Bauteil hinzugefügt
fix: Fehlerbehebung im Design
docs: Änderungen an der Dokumentation
style: Layoutänderungen ohne funktionale Auswirkungen (z.B. Bauteil-Platzierung)
refactor: Design-Optimierung ohne funktionale Änderungen
test: Hinzufügen oder Korrigieren von Testpunkten
fab: Änderungen bezogen auf Fertigung oder Bestückung

Übrigens: zumindest GitHub und Gitlab erkennen diese Patterns und können automatisch Issues schließen, Releases erstellen und sogar Deployment-Pipelines triggern. Wenn ihr also euren Issuetracker auch auf Gitlab laufen lasst, könnt ihr diese Schlüsselwörter fürs automatische Schliessen von Issues verwenden:

close, closes, closed
fix, fixes, fixed
resolve, resolves, resolved

Wenn ihr diese Schlüsselwörter verwendet, gefolgt von der Nummer des Issues, aber ohne "issue" im Text, sondern ´closes #45´, dann werden die entsprechenden Issues geschlossen.

2. Die Zusammenfassung

Die erste Zeile sollte nicht länger als 50-72 Zeichen sein und prägnant beschreiben, was geändert wurde. Sie sollte im Imperativ formuliert sein, beispielsweise "Füge Spannungsregler hinzu" statt "Spannungsregler hinzugefügt". Üblich ist auch, am Ende der Commit-Message keinen Punkt zu machen.

3. Detaillierte Beschreibung

Nach einer Leerzeile folgt bei Bedarf eine ausführlichere Erklärung. Hier kannst du das "Warum" erläutern und Kontext zur Änderung geben.

4. Referenzen

Am Ende kannst du auf relevante Issues, Tickets oder andere Commits verweisen, z.B. "Fixes #123" oder "Related to: #456".

Beispiele für gute Commit-Messages

Schlecht:

Fehler behoben

Gut:

fix(powersupply): Korrigiere Überhitzungsproblem bei hoher Last

Die Temperaturregelung des Spannungsreglers hatte unter Volllast
einen Schwellwert von 85°C, wodurch es zu Leistungsabfällen kam.
Der Schwellwert wurde auf 75°C herabgesetzt, um ausreichend
Kühlreserve zu gewährleisten.

Fixes #289

Weitere Beispiele aus der Hardware-Entwicklung:

feat(sensor): Füge Temperatursensor zur Überwachung hinzu

Der DS18B20 ermöglicht präzise Temperaturmessung mit 0,5°C Genauigkeit.
Platziert auf der Rückseite nahe dem Hauptprozessor.

Related to: #145

style(layout): Optimiere Bauteilplatzierung für bessere EMV

Kondensatoren näher an ICs platziert, Masseflächen vergrößert.
Reduziert potentielle Störungen im 2.4GHz Band.

Was macht Commit-Messages aussagekräftig?

Eine gute Commit-Message sollte folgende Fragen beantworten:

Was wurde geändert? (kurze Zusammenfassung)
Warum wurde es geändert? (Motivation, Problem)
Wie wurde es gelöst? (bei komplexeren Änderungen)
Was sind die Auswirkungen? (Funktionalität, Performance, etc.)

Besonders bei Hardware-Projekten ist es wichtig, auch technische Details zu erwähnen:

Bauteilwerte (z.B. "Widerstand von 1kΩ auf 2.2kΩ geändert")
Toleranzen und Spezifikationen
Fertigungsaspekte (z.B. "Via-Größe für bessere Fertigbarkeit angepasst")
EMV-Überlegungen

Git-Hash auf der Leiterplatte: Maximale Rückverfolgbarkeit

Bei alpha-board gehen wir einen Schritt weiter und sorgen für maximale Nachvollziehbarkeit: Jede produzierte Leiterplatte bekommt automatisch den Git-Commit-Hash im Silkscreen aufgedruckt. So können Fertigungsdaten und das physische Board eindeutig zugeordnet werden.

Wenn beispielsweise ein Kunde ein Problem mit einer Leiterplatte meldet, können wir anhand des Hashes sofort den exakten Stand der Entwicklung identifizieren. Wir sehen dann:

Welche Änderungen zuletzt vorgenommen wurden
Wer die Änderungen durchgeführt hat
Warum die Änderungen gemacht wurden (dank aussagekräftiger Commit-Messages!)

Diese Praxis wollen wir künftig auch in KiCad implementieren, um unseren gesamten Workflow noch transparenter zu gestalten. Bislang machen wir es so bereits in Altium Designer.

Tools für Hardware-Entwicklung

Um die Einhaltung dieser Konventionen zu erleichtern, gibt es hilfreiche Tools, die auch bei Hardware-Projekten nützlich sind:

Commitizen: Ein CLI-Tool zur Erstellung standardisierter Commit-Messages
commitlint: Prüft Commit-Messages auf Einhaltung der Konventionen
Git-Hooks: Automatische Checks vor jedem Commit

Speziell für Hardware-Projekte empfehlen wir zusätzlich:

Regelmäßige Backups der Designdateien (also quasi die Arbeit am lokalen Rechner täglich pushen)
Aussagekräftige Branch-Namen (z.B. "feature/usb-connector", "fix/power-routing", oder unseretwegen auch "develop-gg" für einen Branch, auf dem unser Geschäftsführer Gregor Groß was entwickelt)
Dokumentation von Bauteiländerungen in separaten Dateien

Beispiel: Git Log für ein Hardware-Projekt

Hier ist eine typische git log-Ausgabe für ein Beispielprojekt, das nach den Vorgaben aus diesem Blogpost strukturiert ist:

commit 1a2b3c4d5e6f7g8h9i0j
Author: Max <max@alpha-board.de>
Date:   Fri Jun 13 10:15:00 2025 +0200

    feat(sensor): Füge Temperatursensor zur Überwachung hinzu

    Der DS18B20 ermöglicht präzise Temperaturmessung mit 0,5°C Genauigkeit.
    Platziert auf der Rückseite nahe dem Hauptprozessor.

commit 0j9i8h7g6f5e4d3c2b1a
Author: Anna <anna@alpha-board.de>
Date:   Thu Jun 12 14:30:00 2025 +0200

    fix(powersupply): Korrigiere Überhitzungsproblem bei hoher Last

    Die Temperaturregelung des Spannungsreglers hatte unter Volllast
    einen Schwellwert von 85°C, wodurch es zu Leistungsabfällen kam.
    Der Schwellwert wurde auf 75°C herabgesetzt, um ausreichend
    Kühlreserve zu gewährleisten.

commit 9a8b7c6d5e4f3g2h1i0j
Author: Lisa <lisa@alpha-board.de>
Date:   Wed Jun 11 09:45:00 2025 +0200

    style(layout): Optimiere Bauteilplatzierung für bessere EMV

    Kondensatoren näher an ICs platziert, Masseflächen vergrößert.
    Reduziert potentielle Störungen im 2.4GHz Band.

Fazit

Die Investition in gute Git-Commit Messages zahlt sich durch verbesserte Zusammenarbeit, erleichterte Fehlersuche und bessere Dokumentation vielfach aus. Bei alpha-board haben wir diese Praktiken fest in unseren agilen Hardware-Entwicklungsprozess integriert und profitieren täglich davon.

Ob bei der Entwicklung komplexer PCB-Designs oder der Dokumentation von Fertigungsänderungen – strukturierte Commit-Messages helfen uns dabei, Qualität und Effizienz zu steigern. Kombiniert mit unserem Git-Hash-System auf jeder Leiterplatte erreichen wir eine lückenlose Rückverfolgbarkeit.

Du hast Fragen zur optimalen Integration von Git in deine Hardware-Entwicklungsprozesse? Kontaktiere uns einfach – wir beraten dich gerne!

Wir freuen uns, von Ihnen zu hören

Schreiben Sie uns eine eMail über das Kontaktformular oder ruf Sie uns einfach an. Wir melden uns umgehend.

GIT-COMMIT MESSAGES