Ratgeber

Wenn, dann richtig: So pflegst du einen Changelog

(Foto: Shutterstock)

Ein Changelog ist eine kuratierte, chronologisch geordnete Liste aller wichtigen Änderungen, die an einem Projekt vorgenommen wurden. Warum ihr so einen Log führen solltet und wie das richtig geht.

Warum ihr einen Changelog führen solltet? Ganz einfach: Um es für Nutzer und andere Entwickler leichter zu machen, zu erkennen, welche Änderungen zwischen den einzelnen Releases und Versionen an einem Projekt vorgenommen wurden. Die Endnutzer eurer Software sind schließlich daran interessiert, mitzubekommen, wenn sie sich ändert. Auch wollen weder die Nutzer der Software noch andere Entwickler, 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.

Do:

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 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.

Verschiedene Arten von Änderungen

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.

Das richtige Format für die Datumsangabe

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.

Und wie soll das Dokument heißen?

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.

Don’t:

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 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 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.

Passend dazu: 

Bitte beachte unsere Community-Richtlinien

Wir freuen uns über kontroverse Diskussionen, die gerne auch mal hitzig geführt werden dürfen. Beleidigende, grob anstößige, rassistische und strafrechtlich relevante Äußerungen und Beiträge tolerieren wir nicht. Bitte achte darauf, dass du keine Texte veröffentlichst, für die du keine ausdrückliche Erlaubnis des Urhebers hast. Ebenfalls nicht erlaubt ist der Missbrauch der Webangebote unter t3n.de als Werbeplattform. Die Nennung von Produktnamen, Herstellern, Dienstleistern und Websites ist nur dann zulässig, wenn damit nicht vorrangig der Zweck der Werbung verfolgt wird. Wir behalten uns vor, Beiträge, die diese Regeln verletzen, zu löschen und Accounts zeitweilig oder auf Dauer zu sperren.

Trotz all dieser notwendigen Regeln: Diskutiere kontrovers, sage anderen deine Meinung, trage mit weiterführenden Informationen zum Wissensaustausch bei, aber bleibe dabei fair und respektiere die Meinung anderer. Wir wünschen Dir viel Spaß mit den Webangeboten von t3n und freuen uns auf spannende Beiträge.

Dein t3n-Team

Ein Kommentar
Sebastian Buckpesch

Naja, sehe ich ein wenig anders. Stichwort commitlint, squash commits und semantic-delivery-pipeline.
Marge Requests auf den Master werden gesquasht, sodass unnötige Commits wegfallen. Zudem werden sowieso nur relevante commits in den changelog übernommen.
Mehr Automatisierungsgrad und Standardisierung innerhalb von Den Teams sehe ich kaum. Das setup in der ci/cd pipeline ist nicht komplex und generiert automatisierte, aussagekräftige changelogs und sematische versions (auf basis der commits –> siehe commitlint)

Antworten

Melde dich mit deinem t3n Account an oder fülle die unteren Felder aus.

Bitte schalte deinen Adblocker für t3n.de aus!

Hey du! Schön, dass du hier bist. 😊

Bitte schalte deinen Adblocker für t3n.de aus, um diesen Artikel zu lesen.

Wir sind ein unabhängiger Publisher mit einem Team bestehend aus 65 fantastischen Menschen, aber ohne riesigen Konzern im Rücken. Banner und ähnliche Werbemittel sind für unsere Finanzierung sehr wichtig.

Danke für deine Unterstützung.

Digitales High Five,
Stephan Dörner (Chefredakteur t3n.de) & das gesamte t3n-Team

Anleitung zur Deaktivierung