Changelog schreiben.. doch wie?
Zu vielen Projekten gibt es Changelogs, welche die Änderungen von Version zu Version dokumentieren. Doch wie schreiben wir einen Changelog und was sollte enthalten sein? Diese Fragen wird dieser Artikel behandeln.
Sinn und Zweck
Wozu brauchen wir Changelogs? Bei sehr kleinen Projekten macht es vielleicht wenig Sinn, einen Changelog zu pflegen. Handelt es sich um ein größeres Projekt (eine Anwendung oder große Bibliothek) ist es schön, neue Funktionen und Änderungen schnell zu erfassen.
Vor allem bei Major-Releases (die Hauptnummer einer Anwendung ändert sich) gibt es oft breaking-changes oder neue Funktionen, die vorher nicht da waren. Über die Zeit kann man gut sehen, welche Änderungen ein Projekt durchlaufen ist. Man könnte auch die Logs aus dem SVN/GIT/TFS extrahieren. Doch hier schreiben Entwickler oft sehr technische Informationen. Ein Changelog sollte immer so geschrieben sein, dass ein nicht technisch versierter Nutzer die Programmänderungen nachvollziehen kann.
Ich gebe zu, dass ein Changelog ohne technische Hintergründe manchmal sehr schwierig umzusetzen ist. Allerdings sollte (als Kerngedanke) immer der Endanwender im Fokus stehen. Große administrative Änderungen sollten als externes Dokument verlinkt werden.
Aufbau eines Changelogs
Als wichtigstes sollte die Datei „Changelog“ heißen. Sehr oft sehe ich auch Dateien wie „History“ oder „Versions“. Die aktuellste Version steht ganz oben und wird nach unten hin, immer älter. Das vermeidet langes Scrollen, wenn es schon viele Releases gibt.
Ich habe bisher folgenden Aufbau verwendet:
# Changelog
## Version 1.x
### Version 1.1
- Änderung 1
- Änderung 2
- NEW: Neue Funktion
### Version 1.0
- Änderung 1
- Änderung 2
- NEW: Neue Funktion
- FIX: Behobener Fehler
Ich habe auch ein Beispiel auf folgender Homepage gefunden: KeepAChangelog.com . Hier wird auf zweiter Ebene direkt die Version angegeben. Die dritte Ebene ist unterteilt in ADDED, FIXED, DEPRECATED zur Gruppierung von Änderungen. Das ist aus meiner Sicht auch eine schöne Lösung. Wichtig ist, dass die Struktur innerhalb des Dokuments einheitlich ist.
Mögliche Erweiterungen
Sofern die Hosting-Anwendung Markdown parsen kann (z.B. GitHub oder BitBucket), kann zu manchen Punkten ein Ticket referenziert werden.
## Version 1.0
- NEW: Neue Funktion (#1)
Github oder Bitbucket erkennen diese Nummern in dem Changelog und parsen diese automatisch zu einem Link für das Ticket. Je nach Repository könnte beim Veröffentlichen einer neuen Version ein Hook ausgeführt werden. Dieser filtert z.B. anhand von Tags die Tickets der aktuellen Version und fügt diese dem Changelog hinzu. Allerdings ist dabei zu beachten, dass die Tickets entsprechend gepflegt und zugeordnet werden.
Fazit
Aus meiner Sicht sind Changelogs eine sehr gute Möglichkeit, um den Änderungsverlauf kurz und knackig darzustellen. Vor allem große Änderungen oder Breaking-Changes sind schnell und einfach nachvollziehbar. Leider werden Changelogs (aus Sicht meines bisherigen Umfelds) zu wenig geschrieben oder nicht einheitlich.
Wie ist eure Meinung zu Changelogs und wie sieht eure präferierte Struktur aus?
