Zentralisiertes und automatisiertes Changelog

Jede Komponente eines Projekts und jedes Dokument erhalten eine eigene Changelog-Datei im AsciiDoc-Format (.adoc). Diese Datei wird im Folgenden Komponentenchangelog genannt. Dadurch können Änderungen nah am Änderungsort dokumentiert werden und Entwickler und Architekten können einzelne Einträge des Changelogs direkt einer Komponente oder einem Dokument zuordnen. Damit jedoch auch alle Änderungen eines Projekts (Menge aller Komponenten/Dokumente) zentral in einem Dokument zusammengefasst können, wird eine weitere Changelog-Datei im root-Verzeichnis des Projekts angelegt. Diese Changelog-Datei, im Folgenden Projektchangelog genannt, bindet die einzelnen Changelog-Dateien automatisch und nach Release gruppiert ein. Auf diese Weise besitzt jedes Projekt ein zentrales Changelog und (je nach Projekt) mehrere dezentrale Komponentenchangelogs ohne die Einträge redundant verwalten zu müssen.

Abbildung 1. Zusammenführung der einzelnen Komponentenchangelogs

Zum Erstellen und Bearbeiten wird empfohlen, einen Texteditor zu verwenden, der das AsciiDoc Format unterstützt.

Im Folgenden wird beschrieben, wie die einzelnen Changelog-Dateien erstellt und welche Anforderungen an die Struktur und den Inhalt der Changelogs gestellt werden.

1. Anlegen der Changelog-Dateien

Sowohl der Projektchangelog, als auch der Komponentenchangelog werden mit AsciiDoc erstellt. Das Dateiformat ist .adoc.

1.1. Komponentenchangelog

Für jede Komponente und jedes AsciiDoc-Dokument (z.B. Nutzungsvorgaben) wird eine eigene AsciiDoc Datei (changelog.adoc) erstellt. Bei Dokumenten wird diese Datei im gleichen Verzeichnis wie das Dokument selbst abgelegt.

Abbildung 2. Ablageort des Komponentenchangelog für ein Dokument

Bei Komponenten wird diese Datei im root-Verzeichnis der Komponente abgelegt:

Abbildung 3. Ablageort des Komponentenchangelog für eine Komponente

In die Datei wird die Überschrift "Changelog" eingefügt:

Listing 1. Komponentenchangelog Inhalt

[[changelog]]
== Changelog

1.2. Projektchangelog

Die zentrale Projektchangelog-Datei changelog.adoc wird im root-Verzeichnis des Projekts abgelegt:

Abbildung 4. Ablageort des zentralen Projektchangelogs

Initial wird die Datei ebenfalls mit der Überschrift "Changelog" befüllt.

2. Struktur der Changelog-Dateien

Der Aufbau des Projektchangelogs und der Komponentenchangelogs unterscheidet sich und wird im Folgenden erläutert.

2.1. Komponentenchangelog

Der Komponentenchangelog enthält die Changelog-Einträge nach Release gruppiert. Dazu wird für jedes Release ein eigener Release-Tag definiert:

Listing 2. Erstellung Release-Tag im Komponentenchangelog

// tag::release-2.1.0[]

// --> Hier werden die Changelogeinträge für Release 2.1.0 verfasst

// end::release-2.1.0[]


// tag::release-2.0.0[]

// --> Hier werden die Changelogeinträge für Release 2.0.0 verfasst

// end::release-2.0.0[]

Jeder Release-Tag enthält die Versionsnummer des Releases und eine entsprechende Überschrift.

Somit ergibt sich folgender Gesamtaufbau des Komponentenchangelogs:

Listing 3. Gesamtstruktur Komponentenchangelog

[[changelog]]
== Changelog

*Änderungen IsyFact 2.1.0*

// tag::release-2.1.0[]

// --> Hier werden die Changelogeinträge für Release 2.1.0 verfasst

// end::release-2.1.0[]

*Änderungen IsyFact 2.0.0*

// tag::release-2.0.0[]

// --> Hier werden die Changelogeinträge für Release 2.0.0 verfasst

// end::release-2.0.0[]

Die Struktur des Kompontenchangelogs ist damit erfolgreich erstellt.

2.2. Projektchangelog

Im Projektchangelog sollten nach Möglichkeit keine Changelog-Einträge verfasst, sondern ausschließlich die Komponentenchangelogs eingebunden werden. Dazu wird für jedes Release ein eigener Abschnitt erstellt:

Listing 4. Erstellung Release

=== Änderungen IsyFact 2.1.0

// Beginn übergreifende Änderungen

// Ende übergreifende Änderungen

Jeder Abschnitt enthält die Versionsnummer des Releases.

Unterhalb der Releasedefinition ist der Platz für die Beschreibung von komponentenübergreifenden Änderungen vorbehalten, die nicht einzelnen Komponenten zugeordnet werden können. Dieses direkte Einfügen von Einträgen in das Projektchangelog sollte nur in Ausnahmefällen geschehen (siehe Kapitel Projektchangelog.

Anschließend werden die Komponentenchangelogs in das Projektchangelog eingebunden. Dazu wird für jedes Release nur der mit dem Release getaggte Abschnitt der Komponentenchangelogs importiert:

Listing 5. Einbindung der Komponentenchangelogs

=== Änderungen IsyFact 2.1.0

// Beginn übergreifende Änderungen

// Ende übergreifende Änderungen

include::isyfact-standards-doku:einstieg:page$changelog.adoc[tag=release-2.1.0]
...

Mehrere Releases werden wie folgt angelegt:

Listing 6. Gesamtstruktur Projektchangelog

[[changelog]]
== Changelog

=== Änderungen IsyFact 2.1.0

// Beginn übergreifende Änderungen

// Ende übergreifende Änderungen

include::isyfact-standards-doku:einstieg:page$changelog.adoc[tag=release-2.1.0]
...

=== Änderungen IsyFact 2.0.0

// Beginn übergreifende Änderungen

// Ende übergreifende Änderungen

include::isyfact-standards-doku:einstieg:page$changelog.adoc[tag=release-2.0.0]
...

3. Inhalt der Changelog-Dateien

Diese Kapitel beschreibt die Anforderungen an den Inhalt einzelner Changelogeinträge. Changelogs sollen den Entwicklern von IsyFact-Anwendungen Mitgrationsanleitungen liefern, um von einer älteren IsyFact Version auf eine neuere einfach und schnell wechseln zu können. Damit der Changelog diesen Zweck erfüllt, ist es wichtig, dass sowohl die Entscheidung zur Erstellung eines Changelogeintrags, als auch der Inhalt des Eintrags mit Bedacht gewählt wird.

3.1. Komponentenchangelog

In diesen Fällen sollte immer ein Changelogeintrag erstellt werden:

Sicherheitspatches
Datenbankänderungen
Jede Änderung, die der Entwickler und/oder Endanwender von IsyFact-Anwendungen wahrnimmt (Schnittstellenänderungen, neue Funktionen…)
Performanceverbesserungen

In diesen Fällen sollte kein Changelogeintrag erstellt werden:

Änderungen, die nur die Dokumentation betreffen (z.B. Rechtschreibfehler)
Änderungen, die nur Entwickler der IsyFact adressieren (z.B. Refactoring, Unit-Tests)
Fix eines Bugs, der durch eine vorherige Änderung im selben Release erzeugt wurde

Eine knappe Zusammenfassung einer auf ein Release bezogen Änderung ist in den Release Notes zu dokumentieren.

Eine Migrationsanleitung bei Breaking Changes eines Major Releases ist im Migrationsleitfaden zu dokumentieren.

Folgende Anforderungen gelten für den Inhalt eines Changelogeintrags:

Keine Ticketnummern
Keine Kopie der Ticketbeschreibung
Kurz und prägnant
Erläutert, was geändert wurde und wieso es geändert wurde
Enthält weniger Implementierungsdetails, sondern vielmehr das Endresultat

Aufbau

Der Changelogeintrag sollte wie folgt aufgebaut sein:

Kurze und prägnante Beschreibung der Änderung

3.2. Projektchangelog

Der Projektchangelog kann komponentenübergreifende Changelogeinträge aufnehmen, wenn folgende Bedingung erfüllt ist:

Der Changelogeintrag kann nicht einer Komponente zugewiesen werden

An den Changelogeintrag gelten die in Kapitel Komponentenchangelog beschriebenen Anforderungen. Komponentenübergreifende Einträge sind dem gekennzeichneten Bereich hinzuzufügen (vgl. Einbindung der Komponentenchangelogs).