lt-auth-proxy/.gitea/HOWTO_RELEASE.md

📦 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:

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:

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):

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:

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:

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:

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.