antsibull-changelog: Eine Übersicht
Wenn Sie Ansible intensiv nutzen, haben Sie im Laufe der Zeit wahrscheinlich eine Menge Ansible-Code gesammelt: Playbooks, Rollen, Plugins und mehr. Die beste Möglichkeit, Ihre Ansible-Inhalte zu organisieren, besteht darin, sie in einer „Ansible Collection” zusammenzufassen. Dies kann eine private Ansible Collection auf Ihrem Git-Server sein, oder Sie können sie sogar der Ansible-Community über galaxy.ansible.com zur Verfügung stellen.
✉️ Immer einen Schritt voraus – mit unserem Newsletter!
Mit unserem Newsletter erhalten Sie regelmäßig Informationen zu aktuellen IT-Themen und Open-Source-Lösungen – kompakt und relevant.
👉 Jetzt kostenlos anmelden
Um Änderungen im Laufe der Zeit innerhalb Ihrer Ansible Collection zu verfolgen, sollten Sie die Funktionen von antsibull-changelog nutzen.
Überblick
antsibull-changelog vereinfacht den Veröffentlichungsprozess, indem es automatisch eine Datei CHANGELOG.rst mit allen relevanten Informationen erstellt.
Vor einer Veröffentlichung müssen die Beitragenden lediglich sicherstellen, dass jeder Commit ein sogenanntes Changelog-Fragment enthält.
Zum Zeitpunkt der Veröffentlichung liest antsibull-changelog alle verfügbaren Fragmente ein und kombiniert sie zu einer CHANGELOG.rst.
Hier ist ein Beispiel für eine solche CHANGELOG.rst:
======================= Atix.Demo Release Notes ======================= .. contents:: Topics v1.0.0 ====== Major Changes ------------- - nginx - added new role to install nginx Bugfixes -------- - k8s_drain - Fix k8s_drain does not wait for single pod
Installation
antsibull-changelog kann direkt mit pip installiert werden:
$ python3 -m pip install antsibull-changelog
Erste Konfiguration
Führen Sie antsibull-changelog init im Hauptverzeichnis Ihres Collection-Repositories aus, um die Erstkonfiguration zu erstellen.
$ antsibull-changelog init . Created fragments directory "/path/to/repo/changelogs/fragments" Created config file "/path/to/repo/changelogs/config.yaml"
Schreiben eines Changelog-Fragments
antsibull-changelog erstellt die CHANGELOG.rst, indem es die Fragmente unter changelogs/fragments einliest.
Aus diesem Grund liegt es in der Verantwortung jedes Mitwirkenden, bei allen Commits die passenden Fragmente hinzuzufügen.
Die einzigen Ausnahmen sind Commits, die neue Module oder Plugins zu einer Collection hinzufügen: Diese werden automatisch von antsibull-changelog erkannt, solange im entsprechenden Modul-/Plugin-Code ein Schlüssel version_added vorhanden ist.
Changelog-Fragmente werden im yaml-Format geschrieben (wie fast alles, was mit Ansible zu tun hat).
Jeder Abschnitt in einem Changelog-Fragment kennzeichnet eine bestimmte Änderungskategorie (bugfixes, major_changes, etc.) und enthält eine Liste aller Änderungen, die zu dieser Kategorie gehören.
Hier ein Beispiel für ein Changelog-Fragment zu einem Bugfix:
--- bugfixes: - k8s_drain - Fix k8s_drain does not wait for single pod
Die offizielle Dokumentation über Changelog-Fragmente finden Sie hier.
Linting
antsibull-changelog stellt den Unterbefehl lint bereit, mit dem überprüft werden kann, ob die Syntax Ihrer Changelog-Fragmente korrekt ist.
Um dies auszuprobieren, führen Sie einfach im Hauptverzeichnis Ihres Repositories Folgendes aus:
$ antsibull-changelog lint
Wenn keine Ausgabe erscheint, bedeutet dies, dass alles in Ordnung ist.
Umsetzung als Pre-Commit-Hook
Sie können antsibull-changelog lint als Pre-Commit-Hook ausführen, um sicherzustellen, dass Sie niemals Code mit einem ungültigen Changelog-Fragment committen.
Dazu können Sie folgendes Skript unter /path/to/repo/.git/hooks/pre-commit ablegen:
#!/bin/sh # Check that changelog fragments have the correct syntax antsibull-changelog lint
Achtung: Dies setzt voraus, dass Sie antsibull-changelog lokal installiert haben. Ziehen Sie in Betracht, hierfür eine eigene Python-Umgebung zu erstellen.
Umsetzung in einer CI/CD-Pipeline
Alternativ können Sie einen antsibull-changelog-Schritt in Ihrer CI/CD-Pipeline implementieren.
Hier ein Beispiel für eine GitLab CI/CD-Konfiguration:
antsibull-changelog-lint:
stage: linting
image: ${CI_REGISTRY}/:latest
before_script:
- python3 -m pip install antsibull-changelog
- |
[ -f "requirements.yml" ] \
&& ansible-galaxy install -r requirements.yml
script:
- antsibull-changelog lint
Erstellen eines Release
Sobald Sie die passenden Changelog-Fragmente erstellt haben, können Sie ein neues CHANGELOG.rst erzeugen mit:
$ antsibull-changelog release
Standardmäßig aktualisiert dies die Datei CHANGELOG.rst und löscht alle alten Fragmente.
Um die Release-Version zu bestimmen, liest antsibull-changelog den Inhalt der Datei galaxy.yml ein.
Es ist daher sehr wichtig, diese Datei vor jedem Release entsprechend zu aktualisieren.
