| name | release-please |
| description | Release-please automatisierte Versionierung und Release-Pipeline für den pool-controller — End-to-End Flow von Conventional Commit bis zum Firmware-Binary auf GitHub. Für Entwickler, die Releases verstehen, triggern oder troubleshooten wollen. 🇩🇪 Deutsche Trigger: Release, Version, Veröffentlichung, semver, Versionierung, Tag, Changelog, Firmware-Binary, GitHub Release, release-please, Pipeline. |
| keywords | ["release-please","release pipeline","semver","version management","automatic release","firmware release","changelog","github release","version bump","release PR","tag","release workflow","CI release","ota release","version annotation"] |
Release-Please — Pool Controller
Dieses Dokument beschreibt die automatisierte Release-Pipeline des pool-controllers.
Sie basiert auf release-please und
Conventional Commits.
Übersicht
Developer Commit (main)
│ └─ feat:, fix:, chore:, docs:, etc.
▼
release-please-action@v4
│
├─ Scannt Commits seit letztem Tag
├─ Bestimmt nächste Version (Major/Minor/Patch)
└─ Erzeugt / aktualisiert Release PR
│
▼
PR merge (main)
│
▼
release-please-action@v4
│
├─ Erstellt GitHub Release + Tag (v3.x.y)
├─ Aktualisiert CHANGELOG.md
├─ Aktualisiert Versionen in:
│ ├─ platformio.ini (FW_VERSION)
│ └─ src/Version.h (Fallback)
│
▼
build-firmware Job
│
├─ Baut firmware.bin (pio run)
└─ Lädt Binary ins GitHub Release
│
▼
OTA-Update vom Gerät abrufbar
Konfigurationsdateien
release-please-config.json
{
"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
"release-type": "simple",
"packages": {
".": {
"changelog-path": "CHANGELOG.md",
"extra-files": [
{ "type": "generic", "path": "platformio.ini" },
{ "type": "generic", "path": "src/Version.h" }
]
}
}
}
| Feld | Wert | Bedeutung |
|---|
release-type | simple | Kein Package-Manager (kein package.json) — Version aus Tags |
extra-files | platformio.ini, Version.h | Dateien, die release-please beim Bump aktualisiert |
type: generic | — | x-release-please-version-Annotation in der Datei |
.release-please-manifest.json
{ ".": "3.3.0" }
Aktuelle Version des Projekts. Wird von release-please automatisch aktualisiert.
Version-Annotations
platformio.ini (Zeile 37)
'-D FW_VERSION="3.3.0"' # x-release-please-version
Release-please ersetzt den String zwischen den Anführungszeichen auf dieser Zeile.
Der Build-Flag definiert FW_VERSION für den Compiler — die tatsächliche Version im Binary.
src/Version.h (Zeile 11)
#define FW_VERSION "0.0.0"
Fallback für Kompilierung ohne Build-Flag. Wird von release-please auf die
Release-Version aktualisiert, bleibt aber normalerweise hinter dem Build-Flag zurück.
Wichtig: Die x-release-please-version-Annotation MUSS auf derselben Zeile
wie der zu ersetzende String stehen. Ohne diese Annotation wird die Datei ignoriert.
release-please v4 verwendet type: "generic" statt des alten search-regex-Mechanismus.
Release-Pipeline (release.yml)
name: Release
on:
push:
branches: [main]
Job 1: release-please
Läuft bei jedem Push auf main:
- Scannt alle neuen Commits seit dem letzten Release-Tag
- Bestimmt die nächste Version basierend auf Conventional Commit Types:
| Commits enthalten | Bump | Beispiel |
|---|
feat! oder BREAKING CHANGE | Major (X.0.0) | v3.0.0 → v4.0.0 |
feat (mind. einer) | Minor (x.Y.0) | v3.2.0 → v3.3.0 |
fix (nur, keine feat) | Patch (x.y.Z) | v3.3.0 → v3.3.1 |
Nur chore/docs/ci/refactor | Kein Release | — |
-
Erzeugt/aktualisiert einen Release PR mit:
- Berechneter nächster Version im Titel (z. B.
chore(main): release 3.3.1)
- Automatisch generiertem CHANGELOG-Eintrag
- Aktualisierten Versionen in
extra-files
-
Wird der Release PR gemerged, erstellt release-please:
- GitHub Release mit Tag
v3.x.y
- Aktualisiert
CHANGELOG.md auf main
- Aktualisiert
platformio.ini + Version.h auf main
- Setzt Output
release_created = true
Job 2: build-firmware
Läuft NUR wenn release-please einen Release erstellt hat:
needs: release-please
if: needs.release-please.outputs.release_created == 'true'
- Checkout mit
actions/checkout@v6
- Cache:
~/.platformio + .pio (PlatformIO-Framework + Build-Artefakte)
- Installiert PlatformIO via pip
- Baut
firmware.bin: pio run --environment esp32dev
- Lädt
firmware.bin ins GitHub Release hoch:
gh release upload "$TAG_NAME" ".pio/build/esp32dev/firmware.bin#firmware-esp32dev.bin"
Der #firmware-esp32dev.bin-Teil setzt den Anzeigenamen im Release.
Developer Workflow
Normale Entwicklung (kein Release-Wissen nötig)
git checkout -b feat/my-feature
git commit -m "feat(ha): add heater climate entity"
git push
Release manuell triggern
Ein Release wird automatisch erzeugt, sobald ein Release PR gemerged wird.
Der Release PR entsteht automatisch, wenn neue relevante Commits (feat/fix)
auf main kommen.
Soll sofort ein Release erzwungen werden:
git commit --allow-empty -m "fix: trigger immediate patch release"
git push
Release PR manuell mergen
- Release PR in GitHub öffnen (Titel:
chore(main): release x.y.z)
- PR reviewen (CHANGELOG, Version)
- Mergen
- → Release wird automatisch erstellt + Firmware gebaut + Binary hochgeladen
Release-Firmware per OTA installieren
Im WebUI unter System → Check for Updates:
- Gerät prüft GitHub Releases auf neue Version
- Bei neuere Version: Install Update klicken
- Firmware wird direkt vom GitHub Release geladen und geflasht
Troubleshooting
Release PR wird nicht erzeugt
Ursache: Nur Commits ohne Release-Relevanz (chore, docs, ci, refactor)
seit letztem Release.
Fix: Einen fix: oder feat: Commit auf main bringen:
git commit --allow-empty -m "fix: trigger release"
git push
Release PR existiert, wird aber nicht aktualisiert
Ursache: release-please aktualisiert den PR nur bei neuen Commits auf main.
Wenn seit Erstellung des PR nur chore-Commits kamen, bleibt der PR unverändert.
Fix: feat: oder fix: Commit auf main bringen → release-please aktualisiert den PR.
release_created ist false obwohl PR gemerged
Ursache: Der Merge-Commit des Release PR muss von release-please erkannt werden.
Mögliche Probleme:
- Merge-Konflikt beim Mergen → manueller Merge statt PR-Merge-Button
- Branch-Schutzregeln verhindern Auto-Merge
Fix: Release PR über den GitHub PR-Merge-Button mergen (nicht manuell per git merge).
Firmware-Build schlägt fehl
Ursache: Meist Compiler-Fehler oder fehlende Dependencies.
Fix:
- Build lokal testen:
pio run --environment esp32dev
- Fehler beheben
- Neuen
fix: Commit auf main → release-please aktualisiert den Release PR
- Release PR erneut mergen
Firmware-Binary fehlt im Release
Ursache: build-firmware Job war deaktiviert oder fehlgeschlagen.
Fix: Manuell nachreichen:
gh release upload v3.x.y .pio/build/esp32dev/firmware.bin#firmware-esp32dev.bin
Falsche Version im Binary
Ursache: x-release-please-version-Annotation in platformio.ini fehlt oder ist
verschoben.
Fix: Prüfen, dass genau eine Zeile in platformio.ini das x-release-please-version
enthält und die FW_VERSION darauf steht:
'-D FW_VERSION="3.3.0"' # x-release-please-version
Referenzen
