# 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. **`readme.txt`** im Repo-Root im WordPress-Standard-Format. Nur die WP-Metadaten pflegen — der Changelog-Abschnitt wird vom Release-Workflow automatisch aus `CHANGELOG.md` gefüllt:
   ```
   === Plugin Name ===
   Contributors: ideenfabrik
   Tags: …
   Requires at least: 6.0
   Tested up to: 6.4
   Requires PHP: 7.4
   Stable tag: 1.2.3
   License: GPLv2 or later

   == Description ==
   Kurzbeschreibung des Plugins.

   == Changelog ==
   (wird beim Release automatisch aus CHANGELOG.md generiert)
   ```
4. **`CHANGELOG.md`** im Repo-Root — SSOT für den Changelog. Format:
   ```markdown
   # Changelog

   ## v1.2.3 — 2026-04-23

   ### Neu
   - Feature xyz

   ### Gefixt
   - Bug abc

   ---

   ## v1.2.2 — 2026-04-10
   …
   ```

Alle vier Werte (Tag, Plugin-Header-`Version:`, PHP-Konstante, `Stable tag:` in `readme.txt`) müssen identisch sein. Der Pre-Flight-Check im Reusable bricht sonst ab.

**Pflege-Aufteilung:** Changelog-Einträge nur in `CHANGELOG.md` pflegen. `readme.txt` bekommt seine `== Changelog ==` beim Release automatisch generiert — manuelle Einträge dort werden überschrieben.

## Release-Ablauf (Agent/Mensch)

Auf `main`, nachdem alles für die Version gemergt ist:

```bash
# 1. Plugin-Header-Version, Versions-Konstante und Stable tag in readme.txt auf X.Y.Z setzen
# 2. Neuen Block in CHANGELOG.md ergänzen (neueste Version oben)
# 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. Das ZIP enthält `readme.txt` mit der automatisch befüllten `== Changelog ==`-Section.

## 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.
- **„Pflichtdateien fehlen: CHANGELOG.md / readme.txt"** → Datei im Repo-Root anlegen, Commit, Tag neu setzen.
- **„Plugin-Header-Version ≠ Tag"** → `<slug>.php` Version-Zeile korrigieren, Commit, Tag neu setzen.
- **„Konstante ≠ Tag"** → Versions-Konstante im PHP anpassen, Commit, Tag neu setzen.
- **„Stable tag ≠ Tag"** → `Stable tag:` in `readme.txt` korrigieren, Commit, Tag neu setzen.
- **„Kein Changelog-Block für v…"** → Block `## v1.2.3 — <Datum>` in `CHANGELOG.md` 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.