chore: add automated release workflow and scripts for version management
This commit is contained in:
198
.gitea/HOWTO_RELEASE.md
Normal file
198
.gitea/HOWTO_RELEASE.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# 📦 HOWTO: Release erstellen mit Auto-Changelog-Workflow
|
||||
|
||||
Dieses Repository nutzt einen automatisierten CI/CD-Workflow zur **Versionsverwaltung, Changelog-Generierung und Release-Erstellung**.
|
||||
Der gesamte Prozess ist deklarativ und läuft automatisch – ausgelöst durch Änderungen an einer Datei: `VERSION`.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Was passiert automatisch?
|
||||
|
||||
Sobald Änderungen in `main` landen, prüft der Workflow:
|
||||
|
||||
- 🔍 **Hat sich die Datei `VERSION` geändert?**
|
||||
- ❌ **Nein** → es wird nur das `CHANGELOG.md` aktualisiert (unreleased Abschnitt)
|
||||
- ✅ **Ja** → es wird:
|
||||
- ein vollständiger Changelog für diese Version erzeugt
|
||||
- ein Git-Tag `vX.Y.Z` erstellt
|
||||
- ein Release in Gitea veröffentlicht (inkl. Beschreibung aus dem Changelog)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Wie erzeuge ich ein Release?
|
||||
|
||||
### 1. Erhöhe die Version in der Datei `VERSION`
|
||||
|
||||
Beispiel:
|
||||
|
||||
```txt
|
||||
1.2.3
|
||||
```
|
||||
|
||||
> Diese Datei muss **als eigene Commit-Änderung** erfolgen – idealerweise als letzter Commit in einem PR.
|
||||
> Die Commit-Nachricht sollte mit `chore(version)` beginnen, damit dieser nicht im Changelog auftaucht.
|
||||
|
||||
---
|
||||
|
||||
### 2. Mergen in `main`
|
||||
|
||||
Sobald `main` den Commit mit neuer `VERSION` enthält, wird automatisch:
|
||||
|
||||
- das `CHANGELOG.md` regeneriert und committed
|
||||
- der neue Git-Tag erstellt (`v1.2.3`)
|
||||
- ein Gitea Release mit genau diesem Changelog erzeugt
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Hinweis zu Tokens & Webhooks
|
||||
|
||||
Damit das Release auch korrekt weitere Workflows auslösen kann (z. B. über `on: release`), ist **ein Personal Access Token notwendig**.
|
||||
|
||||
### 🔐 Secret: `RELEASE_PUBLISH_TOKEN`
|
||||
|
||||
> Lege ein Repository-Secret mit diesem Namen an.
|
||||
> Es sollte ein **Gitea Personal Access Token** mit folgenden Berechtigungen sein:
|
||||
|
||||
- `write:repo`
|
||||
- `write:release`
|
||||
- idealerweise: keine Ablaufzeit
|
||||
|
||||
Wird dieser Token **nicht** gesetzt, fällt der Workflow auf `ACTIONS_RUNTIME_TOKEN` zurück, aber:
|
||||
- Release wird trotzdem erstellt
|
||||
- **⚠️ andere Workflows, die auf `release.published` reagieren, könnten nicht getriggert werden**
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Debugging-Tipps
|
||||
|
||||
- Stelle sicher, dass `VERSION` exakt **eine gültige neue semver-Version** enthält
|
||||
- Achte auf den Commit-Log: Changelog-Commits sind mit `chore(changelog):` gekennzeichnet
|
||||
- Verwende nur `main` als Trigger-Zweig
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Erweiterung
|
||||
|
||||
In `upload-assets.yml` kannst du beliebige Build-Artefakte automatisch an das Release anhängen, sobald es veröffentlicht ist.
|
||||
|
||||
Dafür:
|
||||
- liegt das Script `.gitea/scripts/get-release-id.sh`
|
||||
- sowie `.gitea/scripts/upload-asset.sh` bereit
|
||||
|
||||
Mehr dazu in der Datei: `.gitea/workflows/upload-assets.yml`
|
||||
|
||||
---
|
||||
|
||||
## 🧘 Best Practice
|
||||
|
||||
- Changelog-Generierung nie manuell ausführen
|
||||
- Nur `VERSION` ändern, um ein neues Release auszulösen
|
||||
- Auf `CHANGELOG.md` nie direkt committen
|
||||
- Release-Daten niemals per Hand in Gitea pflegen
|
||||
|
||||
📎 Alles wird versioniert, automatisiert und reproduzierbar erzeugt.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Commit-Gruppierung & Changelog-Erzeugung
|
||||
|
||||
Der Changelog wird auf Basis definierter **Commit-Gruppen** erzeugt.
|
||||
Diese Regeln sind in `cliff.toml` unter `commit_parsers` konfiguriert.
|
||||
|
||||
| Prefix / Muster | Gruppe | Beschreibung |
|
||||
|-------------------------------|---------------------------|--------------------------------------------------|
|
||||
| `feat:` | 🚀 Features | Neue Funktionalität |
|
||||
| `fix:` | 🐛 Bug Fixes | Fehlerbehebungen |
|
||||
| `doc:` | 📚 Documentation | Änderungen an Doku, Readmes etc. |
|
||||
| `perf:` | ⚡ Performance | Leistungsverbesserungen |
|
||||
| `refactor:` | 🚜 Refactor | Reorganisation ohne Verhaltensänderung |
|
||||
| `style:` | 🎨 Styling | Formatierung, Whitespaces, Code-Style |
|
||||
| `test:` | 🧪 Testing | Neue oder angepasste Tests |
|
||||
| `ci:` oder `chore:` (ohne Spezifizierung) | ⚙️ Miscellaneous Tasks | CI-Änderungen, Aufgaben, Wartung etc. |
|
||||
| `chore(changelog)`, `chore(version)`, `chore(release): prepare for`, `chore(deps...)`, `chore(pr)`, `chore(pull)` | *(ignoriert)* | Diese Commits werden im Changelog **ausgelassen** |
|
||||
| Commit-Body enthält `security` | 🛡️ Security | Sicherheitsrelevante Änderungen |
|
||||
| `revert:` | ◀️ Revert | Rückgängig gemachte Commits |
|
||||
| alles andere | 💼 Other | Fallback für nicht erkannte Formate |
|
||||
|
||||
### ✍️ Beispiel:
|
||||
|
||||
```bash
|
||||
git commit -m "feat: add login endpoint"
|
||||
git commit -m "fix: prevent crash on null input"
|
||||
git commit -m "chore(version): bump to 1.2.3"
|
||||
```
|
||||
|
||||
> Nur die ersten beiden erscheinen im Changelog – der dritte wird **automatisch übersprungen**.
|
||||
|
||||
---
|
||||
|
||||
## 🧾 Umgang mit `CHANGELOG.md` beim Mergen und Releasen
|
||||
|
||||
Wenn du automatisiert einen Changelog mit `git-cliff` erzeugst, ist `CHANGELOG.md` ein **generiertes Artefakt** – und kein handgepflegter Quelltext.
|
||||
|
||||
Beim Mergen von Feature-Branches in `main` kann es deshalb zu **unnötigen Konflikten** in dieser Datei kommen, obwohl der Inhalt später sowieso neu erzeugt wird.
|
||||
|
||||
---
|
||||
|
||||
## 🧼 Umgang mit `CHANGELOG.md` in Feature-Branches
|
||||
|
||||
Wenn du mit **Feature-Branches** arbeitest, wird `CHANGELOG.md` dort oft automatisch erzeugt.
|
||||
Das kann beim späteren Merge in `main` zu **unnötigen Merge-Konflikten** führen.
|
||||
|
||||
### ✅ Empfohlene Vorgehensweise
|
||||
|
||||
**Bevor du den Branch mit `main` zusammenführst** (Merge oder Cherry-Pick):
|
||||
|
||||
```bash
|
||||
git rm CHANGELOG.md
|
||||
git commit -m "chore(changelog): remove generated CHANGELOG.md before merge"
|
||||
git push
|
||||
```
|
||||
|
||||
Dadurch:
|
||||
|
||||
* verhinderst du Merge-Konflikte mit `CHANGELOG.md`
|
||||
* wird die Datei bei Feature-Branches nicht mehr automatisch erzeugt
|
||||
* bleibt deine Historie sauber und konfliktfrei
|
||||
|
||||
> 💡 Der Workflow erzeugt `CHANGELOG.md` automatisch **nur**, wenn:
|
||||
>
|
||||
> * die Datei schon vorhanden ist **oder**
|
||||
> * der Branch `main` heißt
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Merge-Konflikte verhindern mit `.gitattributes`
|
||||
|
||||
Damit Git bei Konflikten in `CHANGELOG.md` **automatisch deine Version bevorzugt**, kannst du folgende Zeile in die Datei `.gitattributes` aufnehmen:
|
||||
|
||||
```gitattributes
|
||||
CHANGELOG.md merge=ours
|
||||
```
|
||||
|
||||
Das bedeutet:
|
||||
|
||||
* Beim Merge wird die Version aus dem aktuellen Branch (`ours`) behalten
|
||||
* Änderungen aus dem Ziel-Branch (`theirs`) werden verworfen
|
||||
|
||||
### ✅ So verwendest du es richtig:
|
||||
|
||||
1. **Füge die Regel in `main` hinzu**:
|
||||
|
||||
```bash
|
||||
echo "CHANGELOG.md merge=ours" >> .gitattributes
|
||||
git add .gitattributes
|
||||
git commit -m "chore(git): prevent merge conflicts in CHANGELOG.md"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
2. **Hole sie in deinen Feature-Branch**:
|
||||
|
||||
```bash
|
||||
git checkout feature/xyz
|
||||
git rebase origin/main
|
||||
```
|
||||
|
||||
3. **Ab sofort werden Konflikte in `CHANGELOG.md` automatisch aufgelöst** – lokal.
|
||||
|
||||
> ⚠️ Hinweis: Plattformen wie **Gitea, GitHub oder GitLab ignorieren `.gitattributes` beim Merge über die Web-Oberfläche**.
|
||||
> Führe Merges daher **lokal** durch, wenn du Konflikte verhindern willst.
|
||||
Reference in New Issue
Block a user