michaelschiemer/docs/contributing/pull-requests.md

# Pull Request-Anleitung

Diese Anleitung beschreibt den Prozess für das Erstellen, Überprüfen und Zusammenführen von Pull Requests im Framework-Projekt. Die Einhaltung dieser Richtlinien gewährleistet einen reibungslosen Entwicklungsprozess und eine hohe Codequalität.

## Überblick über den Pull Request-Prozess

Der Pull Request-Prozess besteht aus den folgenden Schritten:

1. **Vorbereitung**: Erstellen eines Issues und eines Feature-Branches
2. **Entwicklung**: Implementieren der Änderungen und Schreiben von Tests
3. **Einreichen**: Erstellen eines Pull Requests
4. **Überprüfung**: Code-Review und Diskussion
5. **Anpassung**: Vornehmen von Änderungen basierend auf dem Feedback
6. **Zusammenführen**: Zusammenführen des Pull Requests in den Hauptbranch

## 1. Vorbereitung

### Issues erstellen

Bevor Sie mit der Arbeit an einer neuen Funktion oder Fehlerbehebung beginnen, sollten Sie sicherstellen, dass ein entsprechendes Issue existiert:

1. Überprüfen Sie die bestehenden Issues, um Duplikate zu vermeiden.
2. Wenn kein passendes Issue existiert, erstellen Sie ein neues Issue mit einer klaren Beschreibung des Problems oder der Funktion.
3. Warten Sie auf Feedback vom Kernteam, um sicherzustellen, dass Ihre geplante Änderung mit der Projektrichtung übereinstimmt.

### Feature-Branch erstellen

Sobald Sie ein Issue haben, an dem Sie arbeiten möchten, erstellen Sie einen Feature-Branch:

```bash
# Aktualisieren Sie Ihren lokalen main-Branch
git checkout main
git pull origin main

# Erstellen Sie einen Feature-Branch
git checkout -b feature/issue-123-kurze-beschreibung
```

Verwenden Sie eine konsistente Benennungskonvention für Branches:
- `feature/issue-XXX-kurze-beschreibung` für neue Funktionen
- `bugfix/issue-XXX-kurze-beschreibung` für Fehlerbehebungen
- `refactor/issue-XXX-kurze-beschreibung` für Refactoring
- `docs/issue-XXX-kurze-beschreibung` für Dokumentationsänderungen

## 2. Entwicklung

### Coding Standards

Stellen Sie sicher, dass Ihr Code den [Coding Standards](code-style.md) des Projekts entspricht. Verwenden Sie die bereitgestellten Linting-Tools, um die Einhaltung der Standards zu überprüfen:

```bash
# PHP-Code überprüfen
vendor/bin/phpcs src tests

# JavaScript-Code überprüfen
npm run lint:js

# CSS-Code überprüfen
npm run lint:css
```

### Tests schreiben

Für jede Änderung sollten entsprechende Tests geschrieben werden:

- **Unit-Tests** für einzelne Klassen und Methoden
- **Integrationstests** für die Interaktion zwischen Komponenten
- **Funktionstests** für die Überprüfung von Benutzerszenarien

```bash
# Tests ausführen
vendor/bin/phpunit

# Spezifische Testdatei ausführen
vendor/bin/phpunit tests/Unit/Framework/Http/RequestTest.php

# Tests mit Code-Coverage-Bericht ausführen
vendor/bin/phpunit --coverage-html coverage
```

### Commit-Richtlinien

Schreiben Sie klare und aussagekräftige Commit-Nachrichten, die den Zweck des Commits beschreiben:

```
feat(component): Kurze Beschreibung der Änderung

Längere Beschreibung mit Details zur Änderung, Motivation und Kontext.
Mehrere Zeilen sind erlaubt.

Fixes #123
```

Verwenden Sie die folgenden Präfixe für Ihre Commit-Nachrichten:
- `feat`: Neue Funktion
- `fix`: Fehlerbehebung
- `docs`: Dokumentationsänderungen
- `style`: Formatierung, fehlende Semikolons usw. (keine Codeänderungen)
- `refactor`: Code-Refactoring
- `test`: Hinzufügen oder Korrigieren von Tests
- `chore`: Änderungen an Build-Prozessen oder Hilfswerkzeugen

### Regelmäßiges Pushen

Pushen Sie Ihre Änderungen regelmäßig in Ihren Remote-Branch:

```bash
git push origin feature/issue-123-kurze-beschreibung
```

## 3. Einreichen

### Vorbereitung für den Pull Request

Bevor Sie einen Pull Request erstellen, stellen Sie sicher, dass:

1. Alle Tests erfolgreich durchlaufen werden.
2. Der Code den Coding Standards entspricht.
3. Die Dokumentation aktualisiert wurde (falls erforderlich).
4. Der Branch auf dem neuesten Stand mit dem Hauptbranch ist.

```bash
# Aktualisieren Sie Ihren Branch mit dem neuesten Stand des Hauptbranches
git checkout main
git pull origin main
git checkout feature/issue-123-kurze-beschreibung
git merge main
git push origin feature/issue-123-kurze-beschreibung
```

### Pull Request erstellen

Erstellen Sie einen Pull Request über die GitHub-Oberfläche:

1. Navigieren Sie zu Ihrem Branch auf GitHub.
2. Klicken Sie auf "Compare & pull request".
3. Füllen Sie die Pull Request-Vorlage aus:
   - Titel: Kurze Beschreibung der Änderung (max. 72 Zeichen)
   - Beschreibung: Detaillierte Beschreibung der Änderung, Motivation und Kontext
   - Referenzieren Sie das zugehörige Issue mit "Fixes #123" oder "Relates to #123"
4. Klicken Sie auf "Create pull request".

### Pull Request-Vorlage

```markdown
## Beschreibung

[Beschreiben Sie hier Ihre Änderungen und den Kontext]

## Motivation und Kontext

[Warum ist diese Änderung erforderlich? Welches Problem löst sie?]

## Art der Änderung

- [ ] Fehlerbehebung (nicht-breaking change, behebt ein Problem)
- [ ] Neue Funktion (nicht-breaking change, fügt Funktionalität hinzu)
- [ ] Breaking change (Fehlerbehebung oder Funktion, die zu Inkompatibilitäten führt)
- [ ] Diese Änderung erfordert eine Dokumentationsaktualisierung

## Wie wurde getestet?

[Beschreiben Sie die Tests, die Sie durchgeführt haben, um Ihre Änderungen zu überprüfen]

## Checkliste:

- [ ] Mein Code folgt dem Codestil dieses Projekts
- [ ] Ich habe Selbstüberprüfung meines Codes durchgeführt
- [ ] Ich habe Kommentare zu meinem Code hinzugefügt, insbesondere in schwer verständlichen Bereichen
- [ ] Ich habe entsprechende Änderungen an der Dokumentation vorgenommen
- [ ] Meine Änderungen erzeugen keine neuen Warnungen
- [ ] Ich habe Tests hinzugefügt, die meine Änderungen beweisen
- [ ] Neue und bestehende Unit-Tests bestehen lokal mit meinen Änderungen
- [ ] Alle abhängigen Änderungen wurden zusammengeführt und veröffentlicht

## Zugehörige Issues

[Verlinken Sie hier zugehörige Issues, z.B. "Fixes #123"]
```

## 4. Überprüfung

### Code-Review-Prozess

Nach dem Erstellen eines Pull Requests wird er von mindestens einem Mitglied des Kernteams überprüft. Der Reviewer wird:

1. Den Code auf Einhaltung der Coding Standards überprüfen.
2. Die Funktionalität und Korrektheit der Änderungen bewerten.
3. Die Testabdeckung überprüfen.
4. Feedback und Verbesserungsvorschläge geben.

### Automatisierte Checks

Jeder Pull Request durchläuft automatisierte Checks:

- **CI-Pipeline**: Führt Tests und Linting-Checks aus
- **Code-Coverage**: Überprüft die Testabdeckung
- **Dependency-Scanning**: Überprüft auf Sicherheitsprobleme in Abhängigkeiten

Alle automatisierten Checks müssen erfolgreich sein, bevor ein Pull Request zusammengeführt werden kann.

### Feedback erhalten und geben

Beim Geben und Erhalten von Feedback:

- Seien Sie respektvoll und konstruktiv.
- Konzentrieren Sie sich auf den Code, nicht auf die Person.
- Erklären Sie Ihre Gedanken und geben Sie Beispiele.
- Stellen Sie Fragen, anstatt Annahmen zu treffen.

## 5. Anpassung

### Änderungen vornehmen

Basierend auf dem Feedback aus dem Code-Review können Sie Änderungen an Ihrem Branch vornehmen:

```bash
# Änderungen vornehmen
git add .
git commit -m "fix: Adressieren von Feedback aus dem Code-Review"
git push origin feature/issue-123-kurze-beschreibung
```

Die neuen Commits werden automatisch zum Pull Request hinzugefügt.

### Konflikte lösen

Wenn Konflikte mit dem Hauptbranch auftreten, müssen Sie diese lösen:

```bash
git checkout main
git pull origin main
git checkout feature/issue-123-kurze-beschreibung
git merge main
# Konflikte lösen
git add .
git commit -m "chore: Merge main und löse Konflikte"
git push origin feature/issue-123-kurze-beschreibung
```

## 6. Zusammenführen

### Anforderungen für das Zusammenführen

Bevor ein Pull Request zusammengeführt werden kann, muss er:

1. Von mindestens einem Mitglied des Kernteams genehmigt werden.
2. Alle automatisierten Checks bestehen.
3. Keine offenen Diskussionen oder Anfragen nach Änderungen haben.

### Zusammenführungsmethoden

Das Projekt verwendet verschiedene Zusammenführungsmethoden je nach Art der Änderung:

- **Squash and merge**: Für kleine Änderungen oder Fehlerbehebungen, um die Commit-Historie sauber zu halten.
- **Merge commit**: Für größere Funktionen, bei denen die einzelnen Commits wichtig sind.
- **Rebase and merge**: Für Änderungen, die eine lineare Historie erfordern.

Die bevorzugte Methode ist "Squash and merge", es sei denn, es gibt einen guten Grund für eine andere Methode.

### Nach dem Zusammenführen

Nach dem Zusammenführen eines Pull Requests:

1. Der Feature-Branch kann gelöscht werden.
2. Das zugehörige Issue wird automatisch geschlossen (wenn "Fixes #123" verwendet wurde).
3. Die Änderungen werden in der nächsten Version des Frameworks enthalten sein.

## Tipps für erfolgreiche Pull Requests

### Kleine, fokussierte Änderungen

Halten Sie Pull Requests klein und fokussiert auf eine einzelne Änderung. Dies erleichtert die Überprüfung und reduziert das Risiko von Konflikten.

### Klare Dokumentation

Dokumentieren Sie Ihre Änderungen gründlich, sowohl im Code als auch in der Pull Request-Beschreibung. Erklären Sie, warum die Änderung notwendig ist und wie sie implementiert wurde.

### Kommunikation

Kommunizieren Sie aktiv mit Reviewern und anderen Mitwirkenden. Beantworten Sie Fragen zeitnah und bitten Sie um Klärung, wenn etwas unklar ist.

### Geduld

Der Review-Prozess kann Zeit in Anspruch nehmen, besonders bei komplexen Änderungen. Haben Sie Geduld und nutzen Sie die Zeit, um Ihre Änderungen zu verbessern.

## Häufige Probleme und Lösungen

### Mein Branch ist veraltet

Wenn Ihr Branch veraltet ist und Konflikte mit dem Hauptbranch hat:

```bash
git checkout main
git pull origin main
git checkout feature/issue-123-kurze-beschreibung
git merge main
# Konflikte lösen
git add .
git commit -m "chore: Merge main und löse Konflikte"
git push origin feature/issue-123-kurze-beschreibung
```

### Ich habe einen Fehler in meinem letzten Commit gemacht

Wenn Sie einen Fehler in Ihrem letzten Commit gemacht haben und ihn noch nicht gepusht haben:

```bash
# Änderungen vornehmen
git add .
git commit --amend
git push origin feature/issue-123-kurze-beschreibung --force
```

**Hinweis**: Verwenden Sie `--force` mit Vorsicht, besonders wenn andere Personen an demselben Branch arbeiten.

### Ich möchte meine Commits aufräumen, bevor ich einen Pull Request erstelle

Wenn Sie Ihre Commits aufräumen möchten, bevor Sie einen Pull Request erstellen:

```bash
# Interaktives Rebase für die letzten n Commits
git rebase -i HEAD~n

# Pushen Sie die Änderungen
git push origin feature/issue-123-kurze-beschreibung --force
```

## Weitere Informationen

- [Coding Standards](code-style.md): Erfahren Sie mehr über die Coding Standards des Projekts.
- [Dokumentations-Anleitung](documentation.md): Erfahren Sie, wie Sie zur Dokumentation beitragen können.
- [GitHub Flow](https://guides.github.com/introduction/flow/): Eine leichtgewichtige, branchbasierte Workflow-Anleitung.
- [Architekturübersicht](../architecture/overview.md): Überblick über die Architektur des Frameworks.