Letzte Änderung am 28. Dezember 2021 by Christoph Jüngling
Zu diesem Thema ist natürlich schon viel geschrieben worden, daher will ich mich hier auf das Wesentliche beschränken und ein paar Tipps für die Praxis geben. Zum Einen stellt ihr euch sicher die Frage, wieso ich die Quellcodeverwaltung zum Thema “Dokumentation” hinzu rechne.
Um es kurz zu machen: Wer sagt denn, dass Dokumentation nur für Anwender da ist? Auch Entwickler freuen sich über vernünftige und hilfreiche Beschreibungen! Und da die Quellcodeverwaltung für einen Entwickler so etwas wie ein Tagebuch darstellt, sollte man ruhig ein wenig Konzentration dabei aufbringen.
Was packen wir also in die Commit-Messages hinein:
- Was habe ich gemacht?
- Wie habe ich es gemacht, und warum gerade so?
- Welcher Bugreport bzw. welches Requirement hat diese Änderung ausgelöst?
Dies alles sollte so detailliert wie nötig beschrieben werden, ohne sich dabei in epischer Breite über den Sinn des Lebens auszulassen. Schau dir mal deine eigenen alten Commit-Messages an und frage dich ehrlich, ob du noch verstehst, was du damals gemacht hast :-)
Links zum Bugtracker
Ein wichtiger Punkt ist die Verknüpfung zwischen Bugtracker und Quellcodeverwaltung. Im Git-Log wollen wir die Bugnummer eintragen und auch sehen, während der Git-Server diese dann hoffentlich dem Bugtracker auf irgendeine Weise mitteilt. So sind beide Seiten mit der jeweils anderen verbunden und eine Navigation ist hin und her mit Mausklicks möglich.
Wenn wir einen Cloud-Anbieter wie GitLab, Github oder Bitbucket verwenden, ist diese Verbindung schon immanent (oder kann zumindest mit wenigen Klicks aktiviert werden). Sind es isolierte Programme, muss der Administrator die gegenseitige Verlinkung und vor allem Benachrichtigung einrichten. Darum soll es hier aber nicht gehen.
Eine Voraussetzung dabei ist natürlich, dass wir ein Format finden, dass beide Seiten verstehen. Zumindest TortoiseGit kann von uns ziemlich frei konfiguriert werden. Zusätzlich hilft es uns auch noch bei der Einhaltung des richtigen Formates.
In TortoiseGit (Settings / Issue Tracker Config) tragen wir dazu auf Projekt-Ebene ein, wie die Verlinkung zu Bugs erfolgt, wodurch eine Bugnummer sowohl optisch hervorgehoben wird, als auch klickbar ist. Dies wird in der Datei .tgitconfig
im Hauptverzeichnis des Projektes gespeichert, daher sollte diese Datei auch in die Quellcodeverwaltung aufgenommen werden.
Der erste reguläre Ausdruck bestimmt, wie die Bugnummer grundsätzlich im umgebenenden Text idendifiziert wird. Der zweite Ausdruck (durch einen Zeilenvorschub vom ersten getrennt) definiert, wie die Nummer in die URL übernommen wird.
An der Stelle in der URL, wo die Bugnummer stehen soll, wird einfach %BUGID%
eingetragen. Dieser Platzhalter wird dann von TortoiseGit automatisch durch die gefundene Nummer ersetzt.
Detaillierte Informationen dazu findest du in der Doku von TortoiseGit.
[bugtraq] url = "https://SERVER/PROJECT/issues/%BUGID%" warnifnoissue = true logregex = "#\\d+\n\\d+" append = true number = true message = "Issue #%BUGID%" label = Issue:
Damit wird in TortoiseGit ein zusätzliches Eingabefeld für die Bugnummer angezeigt. Das Feld ist mit “Issue:” bezeichnet, die Bugnummer darf im Beispiel tatsächlich nur ein numerischer Wert sein (number = true) und wird in der Weise “Issue #1234” (message = …) an die Commit-Message angehängt (append = true).
Ein Muster für die Commit-Message
Wer Wert darauf legt, dass die Entwickler die Commit-Messages nach einem immer gleichen Muster ausfüllen, kann bei Git eine Muster-Commitmessage hinterlegen. Dieses Muster wird dann immer bei einem neuen Commit angezeigt. Dabei werden mit einem # beginnende Zeilen in der gespeicherten Commit-Message nicht enthalten sein. Dies eignet sich gut, um kurze Anweisungen zu hinterlegen.
In der Datei .git/config:
[commit] template = .gitmessage
In der Datei .gitmessage:
Kurzbeschreibung (#12345) Beschreibe, was getan wurde und warum. # Deine Eingabe ersetzt diesen Text! # Zeilen bitte bei Spalte 72 umbrechen
Bitte beachte, dass Dateien, die mit einem Punkt beginnen, unter Windows nur in der Konsole angelegt werden können. Der Windows-Explorer verweigert dies leider mit einer Fehlermeldung:
Gib statt dessen in der Konsole einen der folgenden Befehle ein. Mit installierten Unix Utilities funktioniert bereits der erste, der Echo-Befehl funktioniert unter Windows immer.
touch .gitmessage
echo > .gitmessage
Neueste Kommentare