In meinen zahlreichen Softwareprojekten werden täglich Features hinzugefügt, verändert, entfernt oder Bugs gefixt. Dazu gibt es noch unzählige Versionsnummern und noch Bereitstellungen in mehreren Umgebungen. Meine Kolleginnen und Kollegen schreiben alle Veränderungen in ein softwaregestütztes Changelog.
Soweit so gut.
Mich stört allerdings, dass die Changelogs nicht in einem einheitlichen Format geschrieben werden. In dem einen Projekt werden Veränderungen in Stichpunkten notiert, in anderen werden ganze Absätze geschrieben. Was aber hinzugefügt oder gefixt wurde, ist nicht auf einen Blick ersichtlich.
Nach etwas Recherche im Internet bin ich auf Olivier Lacan aufmerksam geworden. Olivier betreibt die Seite Keep a changelog und beschreibt in seinen Augen wie ein Changelog aussehen müsste.
Dabei betrachtet er drei Fragen:
- Was ist ein Changelog
- Was ist der Zweck eines Changelogs
- Wer braucht ein Changelog
Unabhängig von dem Speicherformat ist ein Changelog eine chronologisch sortierte Liste aller erheblichen Änderungen, die zwischen den einzelnen Versionen und Veröffentlichungen eines Projekts umgesetzt wurden. Ein Changelog soll es den Benutzern einfach machen, alle Änderungen zwischen den Versionen zu sehen, und verständlich alle Änderungen in einer Software übersichtlich darstellen.
Olivier fordert auch die Einhaltung grundlegender Prinzipien wie:
- Changelogs werden für Menschen geschrieben (Human readable)
- Für jede einzelne Version sollte es einen Eintrag geben (Versioning)
- Änderungen der selben Art, sollten in Bereiche gruppiert werden
- Versionen und Bereiche sollten verlinkt werden
- Die neueste Version kommt als erstes
- Das Release-Datum jeder Version muss angegeben sein
- Gib an, ob du dich an die Semantische Versionierung hältst
Gut, die Art der Versionierung sollte den Teams überlassen sein. Ansonsten würde ich den Prinzipien zustimmen.
Auf welche Weise soll jetzt der Changelog Eintrag geschrieben sein. Das beschreibt Olivier ebenfalls im Abschnitt Arten von Änderungen:
- Added, unter Added werden alle Features notiert, die seit der letzten Version hinzugekommen sind
- Changed, unter Changed werden alle Änderungen an Funktionen seit der letzten Version notiert
- Deprecated, unter Deprecated werden alle Features notiert, die zukünftig entfernt werden
- Removed, unter Removed werden alle Features notiert, die entfernt wurden
- Fixed, unter Fixed werden alle Bugs notiert, die seit der letzten Version aufgetreten sind
- Security, unter Security wird notiert, welche Sicherheitslücken geschlossen wurden und warum der Benutzer aufgefordert ist ein Update auf diese Version durchzuführen
Das folgende Markdown Template könnte hilfreich sein, beim Schreiben von Changelogs:
# Changelog
### Unreleased
- Fokus auf zukünftigte Features
## [VERSION]
Releasedatum: [Releasedatum im Format yyyy-MM-dd]
Solution: [Link to Solution](https://)
### Added
- Stichpunktartig beschreiben, welche Features hinzugekommen sind
### Changed
- Stichpunktartig beschreiben, welche Features geändert wurden
### Deprecated
- Stichpunktartig beschreiben, welche Features nicht mehr benötigt werden
### Removed
- Stichpunktartig beschreiben, welche Features entfernt wurden
### Fixed
- Stichpunktartig beschreiben, welche Bugs gefixt wurden
### Security
- Stichpunktartig beschreiben, welche Sicherheitsanfälligkeiten
behoben wurden und warum auf diese Version aktualisert werden sollte
Mir gefällt dieses Changelog Format und werde es nach und nach in meine Softwareprojekte überführen.