Changelog Automation mit GitHub Actions

Changelog Automation mit GitHub Actions

Die Verbindung zwischen menschlichen Emotionen und der nächsten Versionsnummer eines Projekts kann zu unerwünschten Ergebnissen führen.

Als Entwickler stehen wir oft vor der meist sehr mühsamen und langwierigen Aufgabe, Changelogs mit Tags und speziellen Versionsnamen zu schreiben, die in einem Code-Repository markiert wurden. Daher ist es schön, wenn wir solche Aufgaben automatisieren können.

In diesem Blogbeitrag geht es um Semantic Versioning und darum, wie mit GitHub Actions das Schreiben von Changelogs automatisiert werden kann.

Dieser Blogbeitrag steht in engem Zusammenhang mit einem früheren Beitrag mit dem Titel "Changelog Automation within Gitlab" und stellt eine Beispielimplementierung von Semantic Versioning innerhalb von GitHub vor.

Wie funktioniert das?

Die Verwendung von Semantic Versioning ermöglicht es GitHub, automatisch Changelogs auf der Grundlage von Commit-Nachrichten zu erstellen. Das bedeutet natürlich, dass die Commit-Nachrichten einem bestimmten Format folgen müssen.

• fix: ein Commit des Typs fix behebt einen Fehler/Bug in Ihrer Codebasis (dies entspricht PATCH in Semantic Versioning).
• feat: ein Commit vom Typ feat führt eine neue Funktion in die Codebasis ein (dies entspricht MINOR in Semantic Versioning).
• BREAKING CHANGE: ein Commit, das eine Fußzeile BREAKING CHANGE: hat oder ein ! nach dem Typ/Scope anhängt, führt eine brechende API-Änderung ein (entspricht MAJOR in Semantic Versioning). Eine BREAKING CHANGE kann Teil von Commits jeden Typs sein.

GitHub example

In diesem Beispiel verwenden wir die folgende GitHub Action, um Changelogs zu erstellen.

 1name: Releases
 2on:
 3  push:
 4    branches:
 5      - main
 6  pull_request:
 7    branches:
 8      - main
 9
10jobs:
11  changelog:
12    runs-on: ubuntu-latest
13
14    steps:
15      - uses: actions/checkout@v2
16
17      - name: conventional Changelog Action
18        id: changelog
19        uses: TriPSs/conventional-changelog-action@v3.7.1
20        with:
21          github-token: ${{ secrets.GITHUB_TOKEN }}
22          # skip-version-file: 'true'
23
24      - name: create release
25        uses: actions/create-release@v1
26        if: ${{ steps.changelog.outputs.skipped == 'false' }}
27        env:
28          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
29        with:
30          tag_name: ${{ steps.changelog.outputs.tag }}
31          release_name: ${{ steps.changelog.outputs.tag }}
32          body: ${{ steps.changelog.outputs.clean_changelog }}

Natürlich ist es möglich, dieser Pipeline eine Build-Phase hinzuzufügen, in der beispielsweise ein neues Docker-Image erstellt und gepusht wird und der neueste Tag des Docker-Images in das Changelog geschrieben wird.

Wenn diese Pipeline erfolgreich ausgeführt wird, erstellt sie automatisch eine CHANGELOG.md- und eine package.json-Datei, sofern diese nicht bereits vorhanden sind.

Die automatische Erstellung von Dateien kann durch die Angabe weiterer Parameter im GitHub Action-Workflow gesteuert werden. Mit diesen Parametern ist es z.B. möglich, die Erstellung der package.json Datei zu überspringen, indem man skip-version-file: 'true' benutzt. Weitere Details entnehmen Sie bitte der offiziellen Dokumentation.

Wenn die Implementierung erfolgt, nachdem ein Tag mit einer Versionsnummer hinzugefügt wurde, müssen Sie die Datei package.json manuell bearbeiten, damit sie mit der Versionsnummer übereinstimmt, sofern die Datei existiert.

Wenn es kein Git-Tag gibt, das mit einer früheren Version des Projekts verknüpft ist, wird die erste Version 0.1.0 sein, unabhängig davon, um welche Änderung es sich handelt (Fix, Feat, BREAKING CHANGE).

Beispiele für Commit-Nachrichten

FIX: (e.g. v0.1.0 → v0.1.1)

1git commit -m "fix: Nachricht"

FEAT: (e.g. v0.1.1 → v0.2.0)

1git commit -m "feat: Nachricht"

BREAKING CHANGE: (e.g. v0.2.0 → v1.0.0)

1git commit -m "feat: Nachricht" -m "BREAKING CHANGE: Nachricht"