chore(changelog): update unreleased changelog

- Add instructions to avoid merge conflicts in `CHANGELOG.md`
- Provide steps for using `.gitattributes` to automate conflict resolution
- Clarify recommended workflows for feature branches and merging

.gitattributes

@@ -0,0 +1 @@
+CHANGELOG.md merge=ours

.gitea/HOWTO_RELEASE.md

@@ -122,3 +122,77 @@ 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.

.gitea/workflows/release.yml

@@ -71,8 +71,14 @@ jobs:
         run: |
           cargo install git-cliff --version "${{ steps.cliff_version.outputs.version }}" --features gitea
 
-      - name: Generate unreleased changelog
+      - name: Generate unreleased changelog (if file exists or on main)
-        run: git-cliff -c cliff.toml -o CHANGELOG.md
+        run: |
+          if [[ -f CHANGELOG.md || "${GITHUB_REF##refs/heads/}" == "main" ]]; then
+            echo "Generating CHANGELOG.md..."
+            git-cliff -c cliff.toml -o CHANGELOG.md
+          else
+            echo "CHANGELOG.md does not exist and this is not 'main'. Skipping generation."
+          fi
 
       - name: Commit updated CHANGELOG
         run: |

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 
 ### 🚀 Features
 
+- *(workflows)* Conditionally generate changelog - ([2ab6f1b](https://git.0xmax42.io/maxp/http-kernel/commit/2ab6f1b8db2d7bd31ca30248d0de183f17a5738c))
 - *(interfaces)* Add pipeline executor interface - ([927a908](https://git.0xmax42.io/maxp/http-kernel/commit/927a9081d4f363202520d017eb424c7c097ced94))
 - *(pipeline)* Add configuration and hooks for pipeline execution - ([3f114bb](https://git.0xmax42.io/maxp/http-kernel/commit/3f114bb68d94c48a53514752d57cb4f01adeaae3))
 - *(workflows)* Add CI for Deno project tests - ([9d5db4f](https://git.0xmax42.io/maxp/http-kernel/commit/9d5db4f414cf961248f2b879f2b132b81a32cb92))
@@ -20,12 +21,14 @@ All notable changes to this project will be documented in this file.
 
 ### 📚 Documentation
 
+- *(release)* Update guidelines for handling changelog - ([6ce73c1](https://git.0xmax42.io/maxp/http-kernel/commit/6ce73c14fa6736b622e646feb61522e6ec1f4c5a))
 - *(pipeline)* Add design plan for PipelineExecutor class - ([0846dbb](https://git.0xmax42.io/maxp/http-kernel/commit/0846dbb758ba788f969a381c56498920ee0f9562))
 - Add README for HttpKernel project - ([a1ce306](https://git.0xmax42.io/maxp/http-kernel/commit/a1ce30627c68a3f869eb6a104308322af8596dc1))
 - Add MIT license file - ([5118a19](https://git.0xmax42.io/maxp/http-kernel/commit/5118a19aeaa1102591aa7fe093fdec1aa19dc7f5))
 
 ### ⚙️ Miscellaneous Tasks
 
+- *(git)* Ignore merge conflicts for CHANGELOG.md - ([d04dfcd](https://git.0xmax42.io/maxp/http-kernel/commit/d04dfcd63ea2478ffdff2e966d310194dafd8d7d))
 - *(workflows)* Refine branch handling in release process - ([8f94cc9](https://git.0xmax42.io/maxp/http-kernel/commit/8f94cc915c75a11efa1a8e3bdc51ffea9c2f19b5))
 - *(workflows)* Update changelog file extension to .md and revert b9d25f23fc - ([a88b4d1](https://git.0xmax42.io/maxp/http-kernel/commit/a88b4d112f5c07664d41f6e9d03246307551f25d))
 - Rename changelog and readme files to use .md extension - ([4f2b650](https://git.0xmax42.io/maxp/http-kernel/commit/4f2b65049f461ef377e7231905fd066cbc3c7fe0))