113 lines
4.1 KiB
Markdown
113 lines
4.1 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. **`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.
|