Add plugin caller template documentation

Kurze Anleitung für Plugin-Repos, wie sie den Reusable release-plugin-Workflow einhängen — inkl. Voraussetzungen, Release-Ablauf, Pinning-Empfehlung und Fehlerdiagnose.
2026-04-23 10:09:37 +00:00
parent 9202ce1c32
commit 35d9dcfabf
1 changed files with 84 additions and 0 deletions
@@ -0,0 +1,84 @@
+# Plugin-Caller-Workflow — Template
+
+Jedes Plugin-Repo (`ideenfabrik/idf-<slug>`) bekommt genau diese eine Datei, um den Release-Mechanismus zu aktivieren:
+
+## Datei: `.gitea/workflows/release.yml`
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+jobs:
+  release:
+    uses: ideenfabrik/idf-ci/.gitea/workflows/release-plugin.yml@v1
+    with:
+      slug: idf-<plugin-slug>
+    secrets: inherit
+```
+
+**Nur `slug` anpassen** — exakt der Plugin-Slug (= Repo-Name ohne Org-Präfix, z. B. `idf-login-branding`).
+
+## Voraussetzungen im Plugin-Repo
+
+Damit der Reusable Workflow durchläuft, müssen im Plugin-Repo vorhanden sein:
+
+1. **`<slug>.php`** — Plugin-Haupt-PHP mit standardmäßigem Plugin-Header, inklusive Zeile `Version: X.Y.Z`.
+2. **Versions-Konstante** in einer PHP-Datei des Plugins:
+   `define('IDF_<UPPER_SLUG_OHNE_IDF_>_VERSION', 'X.Y.Z');`
+   Beispiel: Für `idf-login-branding` → `IDF_LOGIN_BRANDING_VERSION`.
+3. **`CHANGELOG.md`** im Repo-Root mit einem Block für die zu veröffentlichende Version im Format:
+   ```markdown
+   ## v1.2.3 — 2026-04-23
+
+   ### Neu
+   - …
+
+   ### Gefixt
+   - …
+   ```
+
+Alle drei Werte (Tag, Header, Konstante) müssen identisch sein. Pre-Flight-Check im Reusable bricht sonst ab.
+
+## Release-Ablauf (Agent/Mensch)
+
+Auf `main`, nachdem alles für die Version gemergt ist:
+
+```bash
+# 1. Plugin-Header-Version und Versions-Konstante auf X.Y.Z setzen
+# 2. CHANGELOG.md-Block anlegen
+# 3. Commit
+git add -A
+git commit -m "Release v1.2.3"
+git push
+
+# 4. Tag setzen und pushen
+git tag v1.2.3
+git push --tags
+```
+
+Danach läuft die Action automatisch durch. Bei Erfolg liegt auf Gitea ein Release `v1.2.3` mit dem ZIP `idf-<slug>_v1.2.3.zip` als Asset und dem Changelog-Block als Body.
+
+## Pinning-Empfehlung
+
+Beim `uses:`-Aufruf die Version pinnen:
+
+- `@v1` — rolling, zieht Patches und Minors automatisch mit. Empfohlen für die meisten Plugins.
+- `@v1.2` — Patches ja, Minors nein.
+- `@v1.2.3` — exakt einfrieren. Nur für Plugins, die gegen eine bestimmte Workflow-Version validiert wurden.
+
+Breaking Changes am Reusable Workflow → neuer Major (`v2`). Plugin-Repos müssen dann bewusst auf `@v2` wechseln.
+
+## Fehlerdiagnose
+
+Bei abgebrochenem Release:
+
+- **„Tag entspricht nicht vMAJOR.MINOR.PATCH"** → Tag falsch formatiert. Alten Tag löschen (`git tag -d vX && git push origin :refs/tags/vX`), neu taggen.
+- **„Plugin-Header-Version ≠ Tag"** → `<slug>.php` Version-Zeile korrigieren, Commit, Tag neu setzen.
+- **„Konstante ≠ Tag"** → Versions-Konstante im PHP anpassen, Commit, Tag neu setzen.
+- **„CHANGELOG.md fehlt" / „Kein Block"** → Changelog-Eintrag für diese Version anlegen, Commit, Tag neu setzen.
+- **Release-Anlage fehlgeschlagen** → Wahrscheinlich fehlende Token-Berechtigung. `GITEA_TOKEN`-Secret prüfen oder den Standard `github.token` nutzen.
+
+Wichtig: Ein Tag, unter dem ein Release bereits existiert, kann nicht erneut einen Release erzeugen. Bei Korrekturen eine PATCH-Version höher tagen, nicht denselben Tag neu setzen.