Changelogger: Open Source CLI Tool

Es gibt meines Erachtens zwei Dinge, die viele Entwickler nicht können gerne machen. Das ist zum einen (gute) Dokumentationen schreiben und zum anderen ein vernünftiges Changelog erstellen. Für das letztere habe ich nun ein Tool gebaut: Changelogger.

Das Tool habe ich für ChurchTools gebaut, die Firma wo ich aktuell arbeite. Denn wir brauchten eine einfachere Lösung um Changelogs über den Sprint hinweg zu sammeln. Aber fangen wir mal vorne an.

Change… was?

Ein Changelog ist ein Änderungsprotokoll. Sei es die App aus dem AppStore oder eine Bibliothek für Entwickler. Wenn etwas geändert wurde, ein Fehler behoben ist oder ein neues Feature hinzukam, so sollte das in einem Changelog beschrieben/erwähnt werden.

Sollte ich ein Changelog erstellen?

Ja! Ohne Ausnahme. Denn entweder es sind deine End-Nutzer, die gerne nachsehen wollen welches coole Feature du in deiner App nun eingebaut hast oder andere Entwickler möchten erfahren, ob ein Update auf die neue Version ohne Probleme machbar ist.

Gerade wenn eine Bibliothek so genannte „Breaking Changes“ beinhaltet, also Änderungen die das aktuelle Verhalten ändern und somit deine jetztige Verwendung kaputt machen könnten, dann müssen diese Änderungen erwähnt werden. Ein Changelog ist dafür die beste Lösung.

Keep a Changelog

Der Podcast „The Changelog“ hat ein Interview mit Oliver Lacan veröffentlicht. Oliver hat die Seite keepachangelog.com erstellt, wo er noch mal genauer auf die Fragen eingeht und auch eine gute Vorlage für einen Changelog anbietet. Diese Seite habe ich mir nun als Vorlage genommen um ein CLI Tool zu bauen.

Changelogger

Der Changelogger ist ein PHP CLI Tool um einfacher Changelogs für Änderungen zu erstellen und diese in Git zu tracken. Wenn eine neue Version fertig ist, kann das Tool alle Logs zusammenfassen und strukturiert in die CHANGELOG.md Datei schreiben.

Das Problem

Bei ChurchTools arbeiten wir mit GitLab-Issues und Merge Requests. Soweit so gut. Während eines Sprints kommen aber viele Änderungen zusammen. Von Bug Fixes hinzu Security Issues, neuen Features oder Library Updates. Das alles dokumentieren wir im Changelog für unsere User, dass diese nachlesen können was in der neuen Version so drin ist.

Die Logs haben wir immer im jeweiligen Issue in die Beschreibung gepackt. Das wurde aber auf Dauer etwas nervig. Denn beim Release musste einer manuell alle Issues durchgucken, die Changelogs rauskopieren und zusammenfassen.

Die Lösung

Ich habe etwas recherchiert und bin dabei auf diesen Beitrag von GitLab gestoßen. GitLab hat ein Bash Script geschrieben um Changelog Dateien zu erstellen. D.h. für jede Änderung wird eine YAML Datei erstellt, die mit dem Merge Request gestellt wird.

Warum nicht einfach direkt in die CHANGELOG.md Datei schreiben? Das führt sehr schnell zu Merge Conflicts, wenn mehrer Leute die gleich Zeile bearbeiten wollen, was am Anfang eines Sprints oft passiert.

Der Vorteil mit eigenen Dateien liegt somit auf der Hand. Keine Konflikte und man sieht sofort als Reviewer, ob ein Changelog mitgeliefert wurde oder ob der noch fehlt.

Release-Day

Wenn alles soweit fertig ist, dann kann der Changelogger alle unveröffentlichten Änderungen automatisch einlesen und in die CHANGELOG.md Datei schreiben. Das Ganz orientiert sich an keepachangelog.com und sieht somit immer sauber und einheitlich aus.

Verwendung

Ich könnt das Tool gerne in euren Projekt verwenden. Entweder ihr installiert es global oder ladet die PHAR Datei runter. Changelogger ist zwar in PHP geschrieben, aber wie viele andere guten CLI Tools kann man es in jedem Projekt verwenden.

changelogger new # Neuen Log Eintrag erstellen
changelogger release <tag> # Unveröffentlichte Logs in CHANGELOG.md schreiben
changelogger show # Liste alle unveröffentlichten Änderungen

Beta Hinweis

Wir verwenden das Tool schon bei uns, aber es ist noch im Beta Stadium. Es fehlen noch ein paar Dinge, die ich gerne hinzufügen möchte und auch der Code bedarf ein wenig an Refactoring. Wenn euch Dinge ein-/auffallen hinterlasst ein Issue.

Wenn euch das Projekt gefällt und ihr es in einem eurer Projekte verwendet lasst es mich wissen. Entweder hier als Kommentar oder auf Twitter.