managarten/docs/GIT_WORKFLOW.md

Git Workflow Guide

Dokumentation des Git-Workflows für das ManaCore Monorepo.

Branch-Struktur

Branch	Zweck
main	Produktion - stabile Releases
dev	Entwicklung - Integration aller Features
till-dev, {name}-dev	Persönliche Entwicklungs-Branches

Workflow-Übersicht

main (Produktion)
  ↑
  │ PR (nach Testing)
  │
dev (Integration)
  ↑
  │ PR (squashed)
  │
till-dev (Feature-Entwicklung)

Täglicher Entwicklungs-Workflow

1. Auf persönlichem Branch arbeiten

# Sicherstellen, dass du auf deinem Branch bist
git checkout till-dev

# Änderungen committen (viele kleine Commits sind OK)
git add .
git commit -m "feat(app): add feature X"
git commit -m "fix(app): fix bug Y"
git commit -m "refactor(app): cleanup Z"

2. Vor dem PR: Commits squashen

Wenn viele Commits angesammelt sind, sollten diese vor dem PR gequasht werden, um:

• Merge-Konflikte zu minimieren
• Die Git-History sauber zu halten
• Code-Reviews zu vereinfachen

# Anzahl der Commits seit dev zählen
git log --oneline origin/dev..HEAD | wc -l

# Alle Commits seit dev zu einem squashen
git reset --soft origin/dev

# Einen neuen, zusammengefassten Commit erstellen
git commit -m "feat: descriptive summary of all changes"

# Force-Push zum Remote (überschreibt alte Commits)
git push --force-with-lease

3. Rebase mit dev (falls nötig)

Falls dev sich geändert hat, muss rebased werden:

# Neuesten Stand von dev holen
git fetch origin dev

# Rebase durchführen
git rebase origin/dev

# Bei Konflikten:
# 1. Konflikte lösen
# 2. git add <resolved-files>
# 3. git rebase --continue

# Nach erfolgreichem Rebase pushen
git push --force-with-lease

4. Pull Request erstellen

gh pr create --base dev --head till-dev \
  --title "feat: summary of changes" \
  --body "## Summary
- Feature 1
- Feature 2

## Test plan
- [ ] Test case 1
- [ ] Test case 2"

Squash-Strategie

Wann squashen?

Situation	Aktion
Vor jedem PR	Immer squashen
Bei vielen kleinen Commits (10+)	Squashen empfohlen
Bei Rebase-Konflikten	Erst squashen, dann rebasen
Tägliche Arbeit	Kleine Commits OK

Squash-Commit-Message Format

feat: kurze Zusammenfassung (max 50 Zeichen)

## Neue Features
- Feature 1: Beschreibung
- Feature 2: Beschreibung

## Bug Fixes
- Fix 1: Beschreibung

## Breaking Changes (falls vorhanden)
- Breaking Change 1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Konflikt-Lösung

Einfache Konflikte

# Konflikt in einer Datei
git checkout --ours path/to/file    # Unsere Version behalten
git checkout --theirs path/to/file  # Ihre Version behalten
git add path/to/file
git rebase --continue

pnpm-lock.yaml Konflikte

Diese Datei sollte nie manuell gemerged werden:

# Ihre Version nehmen und neu installieren
git checkout --theirs pnpm-lock.yaml
pnpm install --frozen-lockfile=false
git add pnpm-lock.yaml
git rebase --continue

Gelöschte Dateien

# Datei wurde in dev gelöscht, aber in deinem Branch modifiziert
git rm path/to/deleted/file
git rebase --continue

Rebase abbrechen

git rebase --abort  # Zurück zum Zustand vor dem Rebase

Best Practices

Commit Messages

Verwende Conventional Commits:

Prefix	Verwendung
feat	Neue Features
fix	Bug Fixes
docs	Dokumentation
style	Formatting (kein Code-Change)
refactor	Code-Refactoring
test	Tests hinzufügen/ändern
chore	Build, CI, Dependencies

Scope (optional)

feat(contacts): add duplicate detection
fix(calendar): fix event drag and drop
docs(readme): update installation guide

Branch-Hygiene

# Lokale Branches aufräumen
git branch -d feature-branch  # Gelöschte Branches entfernen

# Remote-Tracking-Branches aufräumen
git fetch --prune

Beispiel: Kompletter Workflow

# 1. Feature entwickeln
git checkout till-dev
# ... viele Commits über mehrere Tage ...

# 2. Vor PR: Status prüfen
git fetch origin dev
git log --oneline origin/dev..HEAD  # 54 commits

# 3. Squashen
git reset --soft origin/dev
git commit -m "feat: major update with network graphs, themes, and more"

# 4. Pushen
git push --force-with-lease

# 5. PR erstellen
gh pr create --base dev --head till-dev --title "feat: major update"

# 6. Nach Merge: Branch aktualisieren
git fetch origin dev
git checkout till-dev
git reset --hard origin/dev

Critical Configuration Files

Protected Files (CODEOWNERS)

The following files are protected via .github/CODEOWNERS and require team lead review:

File	Reason
docker-compose.staging.yml	Staging deployment config
docker-compose.production.yml	Production deployment config
docker/caddy/Caddyfile.*	Reverse proxy configuration
.github/workflows/cd-*.yml	Deployment pipelines

Configuration Conflict Prevention

Problem: When rebasing a long-lived branch, configuration files can accidentally overwrite critical settings (e.g., HTTPS URLs reverted to HTTP).

Solution: Always review configuration files carefully during rebase conflicts:

# During rebase, if docker-compose.staging.yml has conflicts:
git diff HEAD -- docker-compose.staging.yml  # See what changed

# Key things to verify:
# 1. _CLIENT URLs use HTTPS staging domains (not HTTP IP addresses)
# 2. CORS_ORIGINS include all HTTPS staging domains
# 3. Environment variables haven't regressed

Staging URL Rules

NEVER use HTTP IP addresses for _CLIENT variables:

# WRONG - HTTP IP address
PUBLIC_MANA_CORE_AUTH_URL_CLIENT: http://46.224.108.214:3001

# CORRECT - HTTPS staging domain
PUBLIC_MANA_CORE_AUTH_URL_CLIENT: https://auth.staging.manacore.ai

CI Check: The staging-config-check.yml workflow validates this on every PR that touches docker-compose.staging.yml.

Rebase Checklist for Config Files

Before completing a rebase that touched configuration files:

• _CLIENT URLs use https://*.staging.manacore.ai format
• CORS_ORIGINS include all HTTPS staging domains
• No HTTP IP addresses in client-facing URLs
• Caddy config matches docker-compose port mappings

Troubleshooting

"fatal: no rebase in progress"

Der Rebase wurde bereits abgeschlossen oder abgebrochen. Prüfe mit git status.

Force-Push wird abgelehnt

# --force-with-lease ist sicherer als --force
# Falls es trotzdem fehlschlägt, prüfe ob jemand anderes gepusht hat
git fetch origin
git log origin/till-dev..till-dev

Commits verschwunden nach Reset

# Git Reflog zeigt alle Aktionen
git reflog

# Zu einem früheren Zustand zurückkehren
git reset --hard HEAD@{2}

---

Zuletzt aktualisiert: 10.12.2025