Warum ihr einen Changelog führen solltet? Ganz einfach: Um es für Nutzer:innen und andere Entwickler:innen leichter zu machen, zu erkennen, welche Änderungen zwischen den einzelnen Releases und Versionen an einem Projekt vorgenommen wurden. Die Endnutzer:innen eurer Software sind schließlich daran interessiert, mitzubekommen, wenn sie sich ändert. Auch wollen weder die Nutzer:innen der Software noch andere Entwickler:innen, die vielleicht sogar Lust haben, an eurem Open-Source-Projekt mitzuarbeiten, über etwaige Gründe für vorgenommene Änderungen im Dunkeln gelassen werden.

Einen Changelog führt ihr also, um es anderen Menschen einfacher zu machen, sich in eurem Projekt zurechtzufinden. Grundsätzlich gibt es beim Erstellen ein paar Prinzipien, an die ihr euch haltet solltet.

Erstellt unbedingt für jede Version einen separaten Eintrag. Geht dabei chronologisch vor: Die neueste Version kommt jeweils als erstes, die älteste ganz zum Schluss. Dabei solltet ihr jede Version jeweils mit dem Release-Datum versehen.

Versionen und Bereiche solltet ihr sinnvoll verlinken – und zwar am besten so, dass die Leser:innen des Logs möglichst einfach und intuitiv innerhalb des Dokuments navigieren können. Falls ihr euch an die semantische Versionierung haltet: Macht das entsprechend kenntlich.

Für jede Art der Änderung gibt es eine eigene Kennzeichnung, die ihr entsprechend ihrer Bedeutung verwenden solltet:

• Added für neue Features.
• Changed für Änderungen an einem bereits existenten Feature.
• Deprecated für Features, die in zukünftigen Versionen nicht mehr vorhanden sein werden.
• Fixed für Bug-Fixes.
• Removed für Features, die in vorherigen Versionen mit der Deprecated-Flag versehen waren und jetzt in der aktuellen Version entfernt wurden.
• Security als Hinweis für die Nutzer, dass mit dieser Änderung eine Sicherheitslücke geschlossen wurde. Diese Flag beinhaltet also immer auch eine Aufforderung zum sofortigen Upgrade auf die aktuelle Version.

Zukünftige Änderungen, die noch nicht implementiert wurden, solltet ihr in einem separaten Abschnitt, den ihr „Unreleased“ nennt, bereits in euren Changelog aufnehmen. Das hat den Vorteil, dass ihr selbst und alle Leser des Changelogs einen Überblick darüber behaltet, was in naher Zukunft für das Projekt geplant ist. Das Beste an dieser Vorgehensweise: Zum Release-Zeitpunkt könnt ihr diesen Abschnitt einfach nach Released verschieben, mehr Arbeit entsteht euch durch diesen Schritt also nicht.

Für die Angabe eines Datums gibt es tatsächlich einen ISO-Standard: Jahr-Monat-Tag, für den 12. März 2020 wäre die korrekte Datumsangabe folglich 2020-03-12. Um Verwirrungen diesbezüglich auszuschließen, haltet ihr euch am besten an dieses Format.

Für die Benennung des Changelog-Dokuments gibt es leider keinen einheitlichen Standard. Meistens heißt eine Changelog-Datei einfach CHANGELOG.md, seltener auch HISTORY oder NEWS. CHANGELOG.md ist wahrscheinlich die sinnvollste Benennung für eine Datei, die eben genau das beinhaltet: einen Changelog.

Außerdem gibt es ein paar Dinge, die ihr besser lassen solltet: Einfach alle Commits eines Projekts in eurem Changelog zu veröffentlichen, ist nicht die beste Idee. Der Changelog soll Änderungen im Code eures Projekts dokumentieren. Git-Commits können – richtig erstellt – zwar durchaus Informationswert haben, trotzdem finden sich unter den Commits eines Projektes ja auch zig weitere Commits, die für euren Changelog nicht relevant sind. Beispiele hierfür sind etwa Merge-Commits oder Änderungen an der Doku. Und das ist nicht der Sinn eines Changelogs. Der besteht darin, für den Nutzer der Software merkbare Unterschiede nachvollziehbar zu machen und sie vollständig zu dokumentieren.

Eine andere Sache, die eher nicht so cool ist, ist, wenn ihr Features einfach ohne Deprecated-Warnung entfernt. Über den Changelog sollen die Nutzer:innen eurer Software nachvollziehen können, wie sich eure Software verändert, unter anderem, um eben genau solche Änderungen und deren Tragweite zu verstehen. Über die Deprecated-Flag gebt ihr ihnen die Möglichkeit, ihren Code entsprechend der geplanten Änderungen an eurer Software entsprechend anzupassen, um dann problemlos auf die neue Version upgraden zu können, wenn sie dann veröffentlicht wird. Generell sollte ein Changelog veraltete und entfernte Features auf jeden Fall auflisten. Einfach, um auch Nutzer:innen abzuholen, die vielleicht seit mehreren Versionen ihre Projekte nicht auf die neueste Version migriert haben.

Mehr Informationen zum Changelog bietet beispielsweise die Website keepachangelog.com, wer tiefer in die Thematik einsteigen will, kann das zum Beispiel über diese Folge des Changelog-Podcasts tun.