claude
35d9dcfabf
Kurze Anleitung für Plugin-Repos, wie sie den Reusable release-plugin-Workflow einhängen — inkl. Voraussetzungen, Release-Ablauf, Pinning-Empfehlung und Fehlerdiagnose.
85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# 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.
|