From eec8f239681c16e1d42b5f43af1b0cf85e43d012 Mon Sep 17 00:00:00 2001
From: CodeDevMLH <145071728+CodeDevMLH@users.noreply.github.com>
Date: Tue, 6 Jan 2026 02:20:20 +0100
Subject: [PATCH] add doc
---
RELEASE_GUIDE.md | 78 +++++++++++++++++++++++++++++++
git_cheat_sheet.md | 106 ++++++++++++++++++++++++++++++++++++++++++
jprm.md | 104 +++++++++++++++++++++++++++++++++++++++++
setup_cross_update.md | 70 ++++++++++++++++++++++++++++
4 files changed, 358 insertions(+)
create mode 100644 RELEASE_GUIDE.md
create mode 100644 git_cheat_sheet.md
create mode 100644 jprm.md
create mode 100644 setup_cross_update.md
diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md
new file mode 100644
index 0000000..5870db6
--- /dev/null
+++ b/RELEASE_GUIDE.md
@@ -0,0 +1,78 @@
+# Release & Update Guide
+
+Diese Anleitung beschreibt die Schritte, die notwendig sind, um eine neue Version des **MediaBar** Plugins zu veröffentlichen.
+
+## 1. Version erhöhen
+
+Bevor du baust, musst du die Versionsnummer in den folgenden Dateien aktualisieren (z.B. von `1.0.0.0` auf `1.0.1.0`):
+
+1. **`Jellyfin.Plugin.MediaBar/Jellyfin.Plugin.MediaBar.csproj`**
+ Suche nach `...` und ändere die Nummer.
+
+2. **`manifest.json`**
+ Füge einen neuen Eintrag oben in die `versions`-Liste ein (oder bearbeite den vorhandenen, wenn es noch kein Release gab).
+ * `version`: Deine neue Nummer.
+ * `changelog`: Was hat sich geändert?
+ * `timestamp`: Das aktuelle Datum (wird später aktualisiert).
+ * `checksum`: (wird nach dem Build aktualisiert).
+
+### Versionierungsschema: Major.Minor.Build.Revision
+(Beispiel: 1.0.0.0)
+
+1. **Major** (1.x.x.x)
+ * **Bedeutung:** Hauptversion.
+ * **Erhöhen bei:** Inkompatiblen Änderungen (Breaking Changes) oder komplettem Rewrite.
+ * **Folge:** Setzt alle nachfolgenden Zahlen auf 0.
+
+2. **Minor** (x.1.x.x)
+ * **Bedeutung:** Nebenversion.
+ * **Erhöhen bei:** Neuen Features / Funktionen, die abwärtskompatibel sind.
+ * **Folge:** Setzt Build und Revision auf 0.
+
+3. **Build** (x.x.1.x)
+ * **Bedeutung:** Patch / Fehlerbehebung.
+ * **Erhöhen bei:** Bugfixes, Sicherheitsupdates (keine neuen Features).
+ * **Folge:** Setzt Revision auf 0.
+
+4. **Revision** (x.x.x.1)
+ * **Bedeutung:** Feingranularer Zähler.
+ * **Erhöhen bei:** Notfall-Fixes (Hotfixes), automatisierter Erstellung (CI/CD) oder internen Anpassungen.
+
+## 2. Plugin bauen und packen
+
+Führe den folgenden Befehl im Terminal (PowerShell) im Hauptverzeichnis aus. Wir nutzen hier `dotnet build` statt `publish`, um unnötige Dateien zu vermeiden.
+
+```powershell
+dotnet build Jellyfin.Plugin.MediaBar/Jellyfin.Plugin.MediaBar.csproj --configuration Release --output bin/Publish; Compress-Archive -Path bin/Publish/* -DestinationPath bin/Publish/Jellyfin.Plugin.MediaBar.zip -Force; $hash = (Get-FileHash -Algorithm MD5 bin/Publish/Jellyfin.Plugin.MediaBar.zip).Hash.ToLower(); $time = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ"); Write-Output "`n----------------------------------------"; Write-Output "NEUE CHECKSUMME (MD5): $hash"; Write-Output "ZEITSTEMPEL: $time"; Write-Output "----------------------------------------`n"
+```
+
+## 3. Manifest aktualisieren
+
+Nachdem der Befehl durchgelaufen ist, siehst du am Ende eine Ausgabe wie:
+
+```text
+----------------------------------------
+NEUE CHECKSUMME (MD5): ef8654666ffeae9695e660944f644ad3
+ZEITSTEMPEL: 2025-12-15T12:34:56Z
+----------------------------------------
+```
+
+1. Kopiere die **Checksumme**.
+2. Öffne `manifest.json`.
+3. Füge die Checksumme bei deinem Versionseintrag unter `"checksum"` ein.
+4. Kopiere den **Zeitstempel** und füge ihn unter `"timestamp"` ein.
+5. Stelle sicher, dass die `sourceUrl` korrekt auf dein Repository zeigt.
+
+## 4. Veröffentlichen
+
+1. Lade die Datei `bin/Publish/Jellyfin.Plugin.MediaBar.zip` irgendwo hoch (z.B. GitHub Releases).
+2. Stelle sicher, dass die `sourceUrl` im `manifest.json` auf diesen Download zeigt (oder auf das Repo, je nachdem wie Jellyfin das handhabt - meistens ist `sourceUrl` der Link zum ZIP).
+ * *Hinweis:* Wenn du das Plugin über ein Repo hostest, muss die URL im Manifest direkt auf die ZIP-Datei zeigen.
+
+## Zusammenfassung der Dateien
+
+| Datei | Zweck | Änderung nötig? |
+| :--- | :--- | :--- |
+| `Jellyfin.Plugin.MediaBar.csproj` | Definiert die DLL-Version | **Ja** |
+| `build.yaml` | Build-Konfiguration | **Ja** |
+| `manifest.json` | Plugin-Liste für Jellyfin | **Ja** (Version, Hash, Zeit) |
diff --git a/git_cheat_sheet.md b/git_cheat_sheet.md
new file mode 100644
index 0000000..798c3ed
--- /dev/null
+++ b/git_cheat_sheet.md
@@ -0,0 +1,106 @@
+# 🚀 Git Cheat Sheet: Branches, Merge, Rebase & VS Code
+
+## 🌳 Branches (Zweige)
+* **`main`** → Stabiler Stand, Production-ready (Deployment).
+* **`dev`** → Aktive Entwicklung, Sammelbecken für Features.
+
+---
+
+## 🛠 Zusammenführen von Änderungen
+
+### Git Merge
+Führt zwei Zweige zusammen. Git sucht den letzten gemeinsamen Basispunkt und erstellt einen neuen **Merge-Commit**.
+
+```bash
+git checkout dev
+git merge main
+```
+
+| Details | |
+|-----------|--------|
+| Wann? | In Team-Branches, bei bereits gepushten Branches, wenn Stabilität wichtiger als eine saubere History ist. |
+| Vorteile | Sicher, einfach nachvollziehbar, schreibt die History nicht um. |
+| Nachteile | Die History kann bei vielen Merges unübersichtlich ("Spaghetti-Graph") werden. |
+
+### Git Rebase
+Setzt deine Commits neu auf die Spitze eines anderen Branches. Die Commit-IDs werden dabei neu geschrieben.
+
+```bash
+git checkout dev
+git rebase main
+```
+
+| Details | |
+|-----------|--------|
+| Wann? | In lokalen Feature-Branches (bevor sie geteilt werden), um die History sauber zu halten. |
+| Vorteile | Erzeugt eine perfekt lineare, leicht lesbare History. |
+| Nachteile | ⚠️ Gefährlich auf geteilten/öffentlichen Branches. Konflikte müssen ggf. für jeden einzelnen Commit gelöst werden. |
+
+---
+
+## 📦 Temporäres Speichern & Spezialbefehle
+
+### Stash (Das "Regal")
+Speichert uncommitted Changes temporär, um das Arbeitsverzeichnis sauber zu machen, ohne zu committen.
+
+```bash
+git stash # Änderungen "parken".
+git stash pop # Änderungen zurückholen und Stash leeren.
+```
+
+**Wann?** Wenn du schnell den Branch wechseln musst, aber deine Arbeit noch nicht fertig ist.
+
+### Cherry-pick
+Kopiert einen ganz gezielten Commit von einem Branch in deinen aktuellen.
+
+```bash
+git cherry-pick
+```
+
+**Wann?** Wenn ein Bugfix auf dem falschen Branch gelandet ist oder du nur eine einzige Funktion aus einem Feature-Branch brauchst.
+
+---
+
+## 🔄 Checkout & Switch
+
+```bash
+git checkout dev # oder git switch dev – Wechselt zum Branch.
+git checkout -f dev # Force Checkout: Wechselt den Branch und verwirft alle ungespeicherten lokalen Änderungen unwiderruflich! ⚠️
+```
+
+---
+
+## 💻 VS Code Git-Optionen (UI)
+
+VS Code bietet beim Branch-Wechsel oft drei intelligente Optionen an:
+
+* **Migrate Changes ⭐**
+ * Nimmt deine aktuellen Änderungen einfach mit in den neuen Branch.
+ * (Intern: stash → switch → stash pop).
+* **Stash & Checkout**
+ * Parkt deine Änderungen sicher im Stash und wechselt den Branch. Die Änderungen bleiben im Stash, bis du sie manuell wieder herausholst.
+* **Force Checkout ⚠️**
+ * Wechselt den Branch und löscht deine aktuellen, ungespeicherten Änderungen. Nur nutzen, wenn die Arbeit weggeworfen werden kann.
+
+---
+
+## 🔄 Typischer Sync-Workflow
+
+Um den Entwicklungs-Branch aktuell zu halten, nachdem dev in main gemerged wurde:
+
+1. Auf dev entwickeln.
+2. Merge dev → main für das Release.
+3. Zurück auf dev wechseln:
+ ```bash
+ git checkout dev
+ git merge main # (oder rebase), um den neuesten Stand vom Main wieder in Dev zu haben.
+ ```
+
+---
+
+## 🧠 Merksätze
+
+* **Merge** = Historien verbinden (Sicher & Dokumentiert).
+* **Rebase** = Historie neu schreiben (Linear & Sauber).
+* **Stash** = "Ich parke das mal kurz hier."
+* **Migrate Changes** = Sicherer Branch-Wechsel mit "Gepäck".
diff --git a/jprm.md b/jprm.md
new file mode 100644
index 0000000..29ab36f
--- /dev/null
+++ b/jprm.md
@@ -0,0 +1,104 @@
+# Using JPRM (Jellyfin Plugin Repository Manager)
+
+Wenn du mehrere Plugins hast, ist es oft einfacher, den offiziellen **JPRM** (Jellyfin Plugin Repository Manager) zu nutzen. Anstatt dass jedes Plugin sich selbst in die Manifest-Datei "pusht" (wie in deinem aktuellen Script), "pullt" das zentrale Repo automatisch die neuesten Releases deiner Plugins.
+
+## Wie es funktioniert
+1. Du hast ein zentrales Repo (z.B. `jellyfin-plugin-manifest`).
+2. Dort läuft ein Script (JPRM), das eine Liste von deinen Plugin-Repos durchgeht.
+3. Es prüft, ob es neue Releases gibt.
+4. Es baut die `manifest.json` komplett neu.
+
+## Schritt 1: Das zentrale Repo vorbereiten
+
+Erstelle ein neues Repo (oder nimm dein vorhandenes `jellyfin-plugin-manifest`) und erstelle eine Datei namens `config.json` (oder ähnlich), die deine Plugins auflistet.
+
+Beispiel `manifest-config.json` für JPRM:
+```json
+[
+ {
+ "Url": "https://github.com/CodeDevMLH/Media-Bar-Plugin",
+ "Branch": "main",
+ "Package": "Jellyfin.Plugin.MediaBarEnhanced"
+ },
+ {
+ "Url": "https://github.com/CodeDevMLH/Anderes-Plugin",
+ "Branch": "main",
+ "Package": "Jellyfin.Plugin.Anderes"
+ }
+]
+```
+
+## Schritt 2: Der GitHub Workflow (im zentralen Repo)
+
+In deinem **zentralen Repo** erstellst du einen Workflow `.github/workflows/update-manifest.yaml`. Dieser läuft z.B. jede Nacht oder wenn du ihn manuell startest.
+
+```yaml
+name: Generate Manifest
+
+on:
+ workflow_dispatch:
+ schedule:
+ - cron: '0 0 * * *' # Täglich um Mitternacht
+
+jobs:
+ generate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Set up Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.x'
+
+ - name: Install JPRM
+ run: pip install jprm
+
+ - name: Generate Manifest
+ run: |
+ # jprm repo init --help für mehr infos
+ # Hier ein einfaches Beispielkommando (die genauen Flags hängen von deiner Struktur ab)
+ jprm repo build --url https://github.com/CodeDevMLH/Media-Bar-Plugin .
+
+ # Alternativ: Nutze ein fertiges Action-Script oder schreibe ein kleines Python Script,
+ # das die config.json liest und jprm aufruft.
+
+ - name: Commit & Push
+ uses: stefanzweifel/git-auto-commit-action@v4
+ with:
+ commit_message: Update repository manifest
+ file_pattern: manifest.json
+```
+
+*Hinweis: Der offizielle JPRM ist sehr mächtig, aber manchmal etwas komplex in der Einrichtung für einfache Setups. Viele User nutzen stattdessen ein einfacheres Python-Script.*
+
+## Alternative: Einfaches Python Script (Empfohlen für den Start)
+Ein simples Script, das du in deinem zentralen Repo ablegst und im Action-Workflow ausführst:
+
+```python
+import json
+import requests
+import hashlib
+
+# Konfiguration
+PLUGINS = [
+ {"user": "CodeDevMLH", "repo": "Media-Bar-Plugin", "guid": "..."}
+]
+
+FINAL_MANIFEST = []
+
+for p in PLUGINS:
+ # 1. Hole Latest Release vpm GitHub API
+ resp = requests.get(f"https://api.github.com/repos/{p['user']}/{p['repo']}/releases/latest")
+ data = resp.json()
+
+ # 2. Lade assets herunter, berechne Hash
+ # 3. Baue JSON Objekt
+ # ...
+
+# Speichere final_manifest.json
+```
+
+## Fazit
+- **Push-Methode (Deine aktuelle Lösung):** Gut für den Anfang. Du hast sofort Kontrolle. Jedes Plugin "kümmert sich selbst".
+- **Pull-Methode (JPRM):** Besser wenn du 5+ Plugins hast. Das zentrale Repo hat die Hoheit.
diff --git a/setup_cross_update.md b/setup_cross_update.md
new file mode 100644
index 0000000..be92812
--- /dev/null
+++ b/setup_cross_update.md
@@ -0,0 +1,70 @@
+# Anleitung: Automatische Updates für "Plugin B" im Media-Bar Manifest
+
+Damit dein Plugin B (das andere Repo) automatisch seine Version im `manifest.json` des **Media-Bar-Plugin** Repos aktualisiert, musst du die `release_automation.yml` **in Repo B** anpassen.
+
+Das Prinzip ist dasselbe wie beim zentralen Repo: Repo B checkt Repo A aus und updatet sich selbst.
+
+## Schritt 1: Secret anlegen
+Du brauchst ein **PAT (Personal Access Token)**, das Zugriff auf das **Media-Bar-Plugin** Repo hat.
+- Erstelle das Secret `MEDIA_BAR_REPO_PAT` im **Plugin B** Repo.
+
+## Schritt 2: Workflow in Plugin B anpassen
+
+Füge diesen Job-Step am Ende der `release_automation.yml` von **Plugin B** hinzu:
+
+```yaml
+ # ------------------------------------------------------------------
+ # UPDATE MEDIA BAR MANIFEST (Cross-Promotion)
+ # ------------------------------------------------------------------
+ - name: Checkout Media Bar Repo
+ uses: actions/checkout@v4
+ with:
+ repository: CodeDevMLH/Media-Bar-Plugin # <--- Ziel-Repo
+ path: media-bar-repo
+ token: ${{ secrets.MEDIA_BAR_REPO_PAT }}
+
+ - name: Update Entry in Media Bar Manifest
+ shell: bash
+ run: |
+ cd media-bar-repo
+
+ # Info vom aktuellen Release (Repo B)
+ VERSION="${{ env.VERSION }}"
+ HASH="${{ env.ZIP_HASH }}"
+ TIME="${{ env.BUILD_TIME }}"
+ # URL zum Release von Repo B
+ DOWNLOAD_URL="https://github.com/${{ github.repository }}/releases/download/v$VERSION/Jellyfin.Plugin.MeinTollesPlugin.zip" # <--- ANPASSEN
+
+ # GUID von Plugin B (Muss fest hinterlegt sein oder aus dem lokalen manifest kommen)
+ PLUGIN_GUID="a1b2c3d4-..." # <--- GUID von Plugin B HIER EINTRAGEN
+
+ echo "Updating Media Bar Manifest for GUID: $PLUGIN_GUID"
+
+ # Update Logic (findet Eintrag anhand GUID und updatet ihn)
+ jq --arg guid "$PLUGIN_GUID" \
+ --arg hash "$HASH" \
+ --arg time "$TIME" \
+ --arg url "$DOWNLOAD_URL" \
+ --arg ver "$VERSION" \
+ 'map(if .guid == $guid then
+ .versions[0].version = $ver |
+ .versions[0].checksum = $hash |
+ .versions[0].timestamp = $time |
+ .versions[0].sourceUrl = $url
+ else . end)' \
+ manifest.json > manifest.json.tmp && mv manifest.json.tmp manifest.json
+
+ - name: Commit and Push to Media Bar Repo
+ run: |
+ cd media-bar-repo
+ git config user.name "GitHub Action"
+ git config user.email "action@github.com"
+
+ if [[ -n $(git status -s) ]]; then
+ git add manifest.json
+ git commit -m "Auto-Update Plugin B to v${{ env.VERSION }}"
+ git push
+ else
+ echo "No changes needed."
+ fi
+```