Changelog-Automatisierung und ihre Grenzen

Changelog-Automatisierung funktioniert, wenn sie Sammeln, Klassifizieren und Veröffentlichen automatisiert und bei Auswahl und Formulierung aufhört. Automatisiert man alles, liefert man ein formatiertes Git-Log aus; automatisiert man nichts, wird der Changelog stoßweise geschrieben, aus dem Gedächtnis, kurz vor Releases. Die nützliche Frage ist, welche Teile man automatisiert, nicht wie viel.

Projekte zur Changelog-Automatisierung scheitern in eine von zwei Richtungen, und beide sind schon im ersten Design-Meeting vorhersehbar. Automatisiert man zu wenig, ist der Changelog ein Dokument, das jemand aktualisieren soll, was bedeutet, dass es stoßweise aktualisiert wird, von wem auch immer den Kürzeren gezogen hat. Automatisiert man zu viel, wird er zu einem formatierten Git-Log: vollständig, korrekt, und von niemandem gelesen.

Welche Teile eines Changelogs sollten automatisiert werden?

Drei der vier Schritte. Sammeln und Veröffentlichen vollständig; Klassifizieren als ersten Durchgang mit menschlichem Eingriff; Auswahl und Formulierung nie.

Sammeln. Änderungen aus dem Ort holen, an dem sie passieren (Commits, PRs, Tickets), und in eine Liste bringen. Automatisiert das vollständig. Menschen sind schlecht darin, es ist mühsam, und es ist der Schritt, der unter Zeitdruck übersprungen wird. Conventional Commits oder PR-Labels sind das übliche Rohmaterial.

Klassifizieren. Entscheiden, ob etwas Added, Fixed, Changed, Deprecated, Removed oder Security ist. Automatisiert den ersten Durchgang anhand von Commit-Typ oder PR-Label, und lasst einen Menschen eingreifen. Die Genauigkeit liegt hier bei etwa achtzig Prozent allein aus Metadaten, und die falschen zwanzig Prozent konzentrieren sich genau auf die Einträge, die zählen, weil Mehrdeutigkeit mit Bedeutsamkeit korreliert.

Auswahl und Formulierung. Entscheiden, was einer Leserin gesagt werden sollte und wie. Automatisiert das nicht. Das ist der ganze Wert des Formats. Alles andere ist Logistik.

Veröffentlichen. Die fertigen Einträge auf eine Seite, in einen Feed, eine E-Mail, ein In-App-Widget, einen Slack-Kanal bringen. Automatisiert das vollständig, und aus einer Quelle. Hier fließt tatsächlich der meiste manuelle Aufwand hinein, und fast niemand zählt ihn mit. Es ist auch der Schritt, der der Person, die die Änderung angefragt hat, mitteilen kann, dass sie ausgeliefert wurde, was das ganze Thema von Den Feedback-Loop von der Changelog-Seite aus schließen ist. Die E-Mail-Hälfte davon hat ihre eigene Form, in der Produkt-Update-E-Mail-Vorlage.

Der letzte Punkt lohnt sich zum Nachdenken. Teams neigen dazu, den Changelog als Schreibproblem zu sehen, und verbringen dann die meiste Zeit mit Distribution: Einträge in ein E-Mail-Tool kopieren, für In-App umformatieren, in Slack einfügen, eine Doku-Seite aktualisieren. Das Schreiben dauert eine Stunde. Das Kopieren dauert eine Stunde pro Release, für immer, und genau das sollte eine Maschine übernehmen.

Was passiert, wenn sich die Grenze verschiebt?

Verschiebt man sie nach oben, bekommt man einen Git-Dump. Volle Automatisierung aus Commits liefert bump deps, fix flaky test, wip und address review comments vor Kundenaugen aus. Jedes Team, das das gemacht hat, hat danach einen Filter hinzugefügt, und der Filter ist ein wiedereingeführter Auswahlschritt unter anderem Namen, mit schlechterer Ergonomie.

Verschiebt man sie nach unten, bekommt man Schübe. Vollständig manuelles Sammeln bedeutet, Einträge werden zum Releasezeitpunkt aus dem Gedächtnis geschrieben. Das ist der Modus, vor dem Keep a Changelog gleich zu Beginn warnt, und er verschlechtert sich still: Der Changelog sieht gepflegt aus, bis genau in der Woche, in der niemand Zeit hatte.

Wie sieht eine Pipeline für Changelog-Automatisierung aus?

Vier Schritte, mit genau einem menschlichen Tor, dort platziert, wo ein Entwurf öffentlich wird.

1. Beim Merge einen Entwurfseintrag aus dem PR ableiten: Typ aus Label oder Commit-Präfix, Titel als erster Entwurf, Rücklink zum PR, Autor erfasst. In einen Unreleased-Eimer einordnen.
2. Jeder kann jederzeit jeden Entwurf bearbeiten, und Bearbeitungen sind günstig. Die meisten bekommen eine umformulierte Zeile.
3. Ein Release zu schneiden verlangt, dass jeder Eintrag im Eimer entweder bearbeitet oder ausdrücklich als intern markiert wurde. Dieses Tor ist das ganze Design. Ohne es liefern Entwürfe unbearbeitet in der stressigen Woche aus.
4. Veröffentlichen ist ein Fan-out aus der freigegebenen Menge: die öffentliche Seite, der Feed, die E-Mail, das Widget, der Slack-Post. Eine Quelle, mehrere Darstellungen, kein Kopieren.

Schritt 3 ist die einzige Stelle, an der ein Mensch nötig ist, und er dauert etwa zehn Minuten pro Release, sobald die Entwürfe brauchbar sind. Ist eine Kundenanfrage beteiligt, trägt der Entwurf auch das Issue, das er schließt, was Schritt 4 erlaubt, die anfragende Person zu informieren; die Feature-Request-Vorlage ist so gestaltet, dass dieser Link erhalten bleibt. Wo dieser Schritt im weiteren Release-Ablauf sitzt, behandelt der Release-Management-Prozess.

Was verlangt Automatisierung von euren Daten?

Nichts davon funktioniert, wenn der Changelog eine Markdown-Datei ist, denn eine Datei lässt sich nicht ohne erneutes Parsen in fünf Oberflächen rendern, und Prosa zu parsen ist, wie man bei einem Widget landet, das eine halbe Überschrift anzeigt.

Einträge müssen strukturiert sein: ein Typ, ein Datum, eine Version oder Release-ID, eine Zielgruppe, ein Text und ein Link. Dann sind die Datei, die Seite, der Feed und die E-Mail alle nur Ansichten. Dieser strukturelle Punkt ist das Einzige, das sich lohnt, richtig zu machen, bevor man ein Werkzeug wählt, weil es das ist, was man nicht günstig nachrüsten kann. Nichts davon läuft aber, solange nicht für jede Änderung, die es braucht, wirklich ein Eintrag entsteht; einen Changelog-Eintrag in CI erzwingen behandelt, wie man die Pipeline einen Merge ohne Eintrag verweigern lässt, statt diesen Schritt dem Gedächtnis zu überlassen.

Wir bauen changeloop, wo der Changelog zuerst ein Feed und dann erst eine Seite ist, also lies das als Interesse und nicht als unparteiische Empfehlung; die Preise sind ein kostenloses Repository ohne Karte, genug, um die Form zu sehen. Changelog-Tools ist unsere Übersicht, was es sonst noch gibt, einschließlich der Produkte, mit denen wir konkurrieren, und der Changelog-Generator macht die Sammel- und Klassifizierungsschritte im Browser, wenn du die Ableitung sehen willst, bevor du dich auf eine Pipeline festlegst.

Der Test

Zähle die Minuten zwischen einer gemergten Änderung und dem Moment, in dem sie für eine Kundin sichtbar wird, die euer Repo nicht liest. Sind die meisten dieser Minuten jemand, der Text zwischen Werkzeugen kopiert, liegt die nötige Automatisierung beim Veröffentlichen, nicht beim Schreiben.

FAQ

Kann KI den Changelog schreiben? Sie kann einen entwerfen. Ein Modell, dem man den gemergten Pull Request gibt, liefert meistens einen brauchbaren ersten Entwurf für Titel und Text, was die Sammel- und Klassifizierungsschritte besser erledigt. Die Auswahl, ob einer Leserin überhaupt etwas gesagt werden sollte, und die endgültige Formulierung brauchen weiterhin die Person, die die Zielgruppe kennt, und eine Pipeline, die Entwürfe ohne dieses Tor veröffentlicht, hat den falschen Schritt automatisiert.

Was ist der Unterschied zwischen einem Changelog-Generator und Changelog-Automatisierung? Ein Generator verwandelt Commits einmal, auf Abruf, in eine formatierte Liste. Automatisierung läuft bei jedem Merge, hält einen Unreleased-Eimer, verlangt menschliche Prüfung vor dem Release und veröffentlicht auf jede Oberfläche aus einer Quelle. Der Generator ist der erste, von Hand ausgeführte Schritt der Pipeline.

Sollte der Changelog aus Commits oder aus Pull Requests automatisiert werden? Aus Pull Requests, wo die Änderungseinheit der PR ist: Titel und Beschreibung werden einmal geschrieben, für die ganze Änderung, und der PR verlinkt das Issue, das er schließt. Commit-basierte Ableitung funktioniert, wenn Commits die Einheit sind und einer Konvention folgen.

Wie verhindert man, dass Automatisierung interne Änderungen veröffentlicht? Klassifiziert chore, ci, test, refactor und Abhängigkeits-Updates standardmäßig als intern, und macht die Beförderung zu öffentlich zu einem bewussten Akt. Der umgekehrte Standard, öffentlich, sofern niemand es versteckt, ist, wie bump deps Kunden erreicht.

Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.

Mehr bei changeloop: Changelog-Tools im Vergleich, Changelog-Generator