Entwicklungsworkflow

Diese Seite erklärt den Standard-Workflow für die Fess-Entwicklung. Sie können den Ablauf von Entwicklungsarbeiten wie Funktionserweiterungen, Fehlerbehebungen, Tests und Code-Reviews lernen.

Grundlegender Entwicklungsablauf

Die Entwicklung von Fess folgt diesem Ablauf:

1. Überprüfung/Erstellung von Issues
   ↓
2. Erstellung eines Branches
   ↓
3. Codierung
   ↓
4. Ausführung lokaler Tests
   ↓
5. Commit
   ↓
6. Push
   ↓
7. Erstellung eines Pull Requests
   ↓
8. Code-Review
   ↓
9. Antwort auf Review-Feedback
   ↓
10. Merge

Jeder Schritt wird im Detail erklärt.

Schritt 1: Überprüfung/Erstellung von Issues

Überprüfen Sie vor Beginn der Entwicklung die GitHub-Issues.

Überprüfung vorhandener Issues

Besuchen Sie die Fess-Issue-Seite
Suchen Sie nach Issues, an denen Sie arbeiten möchten
Kommentieren Sie das Issue, um mitzuteilen, dass Sie mit der Arbeit beginnen

Tipp

Für Ihren ersten Beitrag empfehlen wir, mit Issues zu beginnen, die das Label good first issue haben.

Erstellung eines neuen Issues

Erstellen Sie bei neuen Funktionen oder Fehlerbehebungen ein Issue.

Klicken Sie auf New Issue
Wählen Sie eine Issue-Vorlage
Füllen Sie die erforderlichen Informationen aus:
- Titel: Klare und verständliche Beschreibung
- Beschreibung: Detaillierter Hintergrund, erwartetes Verhalten, aktuelles Verhalten
- Reproduktionsschritte: Bei Bugs
- Umgebungsinformationen: OS, Java-Version, Fess-Version usw.
Klicken Sie auf Submit new issue

Issue-Vorlagen

Fehlerbericht:

## Problembeschreibung
Kurze Beschreibung des Bugs

## Reproduktionsschritte
1. ...
2. ...
3. ...

## Erwartetes Verhalten
Was sollte passieren

## Tatsächliches Verhalten
Was tatsächlich passiert

## Umgebung
- OS:
- Java-Version:
- Fess-Version:

Feature-Anfrage:

## Funktionsbeschreibung
Beschreibung der hinzuzufügenden Funktion

## Hintergrund und Motivation
Warum diese Funktion benötigt wird

## Vorgeschlagene Implementierungsmethode
Wie sie implementiert werden soll (optional)

Schritt 2: Erstellung eines Branches

Erstellen Sie einen Arbeits-Branch.

Branch-Namenskonventionen

Branch-Namen folgen diesem Format:

<type>/<issue-number>-<short-description>

Typen:

feature: Hinzufügen neuer Funktionen
fix: Fehlerbehebung
refactor: Refactoring
docs: Dokumentationsaktualisierung
test: Hinzufügen/Ändern von Tests

Beispiele:

# Hinzufügen einer neuen Funktion
git checkout -b feature/123-add-search-filter

# Fehlerbehebung
git checkout -b fix/456-fix-crawler-timeout

# Dokumentationsaktualisierung
git checkout -b docs/789-update-api-docs

Schritte zur Branch-Erstellung

Holen Sie sich den neuesten main-Branch:
```
git checkout main
git pull origin main
```

Erstellen Sie einen neuen Branch:

git checkout -b feature/123-add-search-filter

Überprüfen Sie, dass der Branch erstellt wurde:
```
git branch
```

Schritt 3: Codierung

Implementieren Sie Funktionen oder beheben Sie Fehler.

Codierungskonventionen

Fess folgt den folgenden Codierungskonventionen.

Grundlegender Stil

Einrückung: 4 Leerzeichen
Zeilenlänge: maximal 120 Zeichen empfohlen
Kodierung: UTF-8
Zeilenumbruch: LF (Unix-Stil)

Namenskonventionen

Klassennamen: PascalCase (z. B.: SearchService)
Methodennamen: camelCase (z. B.: executeSearch)
Konstanten: UPPER_SNAKE_CASE (z. B.: MAX_SEARCH_SIZE)
Variablen: camelCase (z. B.: searchResults)

Kommentare

Javadoc: Erforderlich für öffentliche Klassen und Methoden
Implementierungskommentare: Fügen Sie Erklärungen auf Japanisch oder Englisch für komplexe Logik hinzu

Beispiel:

/**
 * Führt die Suche aus.
 *
 * @param query Suchanfrage
 * @return Suchergebnisse
 */
public SearchResponse executeSearch(String query) {
    // Abfrage normalisieren
    String normalizedQuery = normalizeQuery(query);

    // Suche ausführen
    return searchEngine.search(normalizedQuery);
}

Umgang mit null

Vermeiden Sie nach Möglichkeit die Rückgabe von null
Verwendung von Optional wird empfohlen
Führen Sie null-Prüfungen explizit durch

Beispiel:

// Gutes Beispiel
public Optional<User> findUser(String id) {
    return userRepository.findById(id);
}

// Zu vermeidendes Beispiel
public User findUser(String id) {
    return userRepository.findById(id);  // Möglichkeit von null
}

Ausnahmebehandlung

Fangen und behandeln Sie Ausnahmen angemessen
Protokollieren Sie Ausgaben
Geben Sie Benutzern verständliche Nachrichten

Beispiel:

try {
    // Verarbeitung
} catch (IOException e) {
    logger.error("Dateilesefehler", e);
    throw new FessSystemException("Datei konnte nicht gelesen werden", e);
}

Logging

Verwenden Sie angemessene Log-Ebenen:

ERROR: Bei Fehlern
WARN: Bei zu warnenden Situationen
INFO: Wichtige Informationen
DEBUG: Debug-Informationen
TRACE: Detaillierte Trace-Informationen

Beispiel:

if (logger.isDebugEnabled()) {
    logger.debug("Suchanfrage: {}", query);
}

Tests während der Entwicklung

Testen Sie während der Entwicklung auf folgende Weise:

Lokale Ausführung

Führen Sie Fess von der IDE oder der Kommandozeile aus und überprüfen Sie den Betrieb:

mvn compile exec:java

Debug-Ausführung

Verwenden Sie den Debugger der IDE, um das Verhalten des Codes zu verfolgen.

Ausführen von Unit-Tests

Führen Sie Tests im Zusammenhang mit Änderungen aus:

# Bestimmte Testklasse ausführen
mvn test -Dtest=SearchServiceTest

# Alle Tests ausführen
mvn test

Weitere Informationen finden Sie unter Bauen und Testen.

Schritt 4: Ausführen lokaler Tests

Führen Sie vor dem Commit unbedingt Tests aus.

Ausführen von Unit-Tests

mvn test

Ausführen von Integrationstests

mvn verify

Überprüfung des Code-Stils

mvn checkstyle:check

Ausführen aller Prüfungen

mvn clean verify

Schritt 5: Commit

Committen Sie Ihre Änderungen.

Commit-Nachrichten-Konventionen

Commit-Nachrichten folgen diesem Format:

<type>: <subject>

<body>

<footer>

Typen:

feat: Neue Funktion
fix: Fehlerbehebung
docs: Nur Dokumentationsänderungen
style: Änderungen, die die Bedeutung des Codes nicht beeinflussen (Formatierung usw.)
refactor: Refactoring
test: Hinzufügen/Ändern von Tests
chore: Änderungen am Build-Prozess oder an Tools

Beispiel:

feat: Suchfilterfunktion hinzugefügt

Benutzer können jetzt Suchergebnisse nach Dateityp filtern.

Fixes #123

Commit-Schritte

Änderungen stagen:
```
git add .
```

Commit:

git commit -m "feat: Suchfilterfunktion hinzugefügt"

Commit-Historie überprüfen:
```
git log --oneline
```

Commit-Granularität

Ein Commit sollte eine logische Änderung enthalten
Teilen Sie große Änderungen in mehrere Commits auf
Commit-Nachrichten sollten verständlich und spezifisch sein

Schritt 6: Push

Pushen Sie den Branch in das Remote-Repository.

git push origin feature/123-add-search-filter

Beim ersten Push:

git push -u origin feature/123-add-search-filter

Schritt 7: Erstellung eines Pull Requests

Erstellen Sie einen Pull Request (PR) auf GitHub.

Schritte zur PR-Erstellung

Besuchen Sie das Fess-Repository
Klicken Sie auf den Tab Pull requests
Klicken Sie auf New pull request
Wählen Sie den Base-Branch (main) und den Vergleichs-Branch (Arbeits-Branch)
Klicken Sie auf Create pull request
Füllen Sie den PR-Inhalt aus (folgen Sie der Vorlage)
Klicken Sie auf Create pull request

PR-Vorlage

## Änderungsinhalt
Was in diesem PR geändert wurde

## Zugehöriges Issue
Closes #123

## Art der Änderung
- [ ] Neue Funktion
- [ ] Fehlerbehebung
- [ ] Refactoring
- [ ] Dokumentationsaktualisierung
- [ ] Sonstiges

## Testmethode
Wie diese Änderung getestet wurde

## Checkliste
- [ ] Code funktioniert
- [ ] Tests hinzugefügt
- [ ] Dokumentation aktualisiert
- [ ] Codierungskonventionen befolgt

PR-Beschreibung

Die PR-Beschreibung sollte Folgendes enthalten:

Zweck der Änderung: Warum diese Änderung notwendig ist
Änderungsinhalt: Was geändert wurde
Testmethode: Wie es getestet wurde
Screenshots: Bei UI-Änderungen

Schritt 8: Code-Review

Betreuer überprüfen den Code.

Review-Aspekte

Im Review werden folgende Punkte überprüft:

Code-Qualität
Einhaltung von Codierungskonventionen
Vollständigkeit der Tests
Auswirkungen auf die Performance
Sicherheitsprobleme
Aktualisierung der Dokumentation

Beispiele für Review-Kommentare

Genehmigung:

LGTM (Looks Good To Me)

Änderungsanfrage:

Ist hier nicht eine null-Prüfung erforderlich?

Vorschlag:

Diese Verarbeitung könnte besser in eine Helper-Klasse verschoben werden.

Schritt 9: Antwort auf Review-Feedback

Reagieren Sie auf Review-Kommentare.

Schritte zur Beantwortung von Feedback

Lesen Sie die Review-Kommentare
Nehmen Sie erforderliche Änderungen vor

Änderungen committen:

git add .
git commit -m "fix: Auf Review-Kommentare reagiert"

Push:

git push origin feature/123-add-search-filter

Antworten Sie auf Kommentare auf der PR-Seite

Antworten auf Kommentare

Antworten Sie immer auf Review-Kommentare:

Korrigiert. Bitte überprüfen Sie.

Oder:

Vielen Dank für Ihren Hinweis.
Aus Gründen von XX habe ich die aktuelle Implementierung gewählt, wie wäre es?

Schritt 10: Merge

Nach Genehmigung des Reviews merged der Betreuer den PR.

Maßnahmen nach dem Merge

Aktualisieren Sie den lokalen main-Branch:
```
git checkout main
git pull origin main
```

Löschen Sie den Arbeits-Branch:

git branch -d feature/123-add-search-filter

Löschen Sie den Remote-Branch (falls nicht automatisch auf GitHub gelöscht):
```
git push origin --delete feature/123-add-search-filter
```

Häufige Entwicklungsszenarien

Funktionserweiterung

Erstellen Sie ein Issue (oder überprüfen Sie ein vorhandenes)
Erstellen Sie einen Branch: feature/xxx-description
Implementieren Sie die Funktion
Fügen Sie Tests hinzu
Aktualisieren Sie die Dokumentation
Erstellen Sie einen PR

Fehlerbehebung

Überprüfen Sie das Fehlerbericht-Issue
Erstellen Sie einen Branch: fix/xxx-description
Fügen Sie einen Test hinzu, der den Fehler reproduziert
Beheben Sie den Fehler
Überprüfen Sie, dass die Tests bestehen
Erstellen Sie einen PR

Refactoring

Erstellen Sie ein Issue (erklären Sie den Grund für das Refactoring)
Erstellen Sie einen Branch: refactor/xxx-description
Führen Sie das Refactoring durch
Überprüfen Sie, dass vorhandene Tests bestehen
Erstellen Sie einen PR

Dokumentationsaktualisierung

Erstellen Sie einen Branch: docs/xxx-description
Aktualisieren Sie die Dokumentation
Erstellen Sie einen PR

Entwicklungstipps

Effiziente Entwicklung

Kleine Commits: Committen Sie häufig
Frühes Feedback: Nutzen Sie Draft-PRs
Testautomatisierung: Nutzen Sie CI/CD
Code-Review: Überprüfen Sie auch den Code anderer

Problemlösung

Nutzen Sie bei Schwierigkeiten Folgendes:

GitHub Discussions
Fess-Forum
GitHub-Issue-Kommentare

Nächste Schritte

Nachdem Sie den Workflow verstanden haben, lesen Sie auch folgende Dokumentation:

Bauen und Testen - Details zu Build und Test
Leitfaden für Beiträge - Richtlinien für Beiträge
Architektur und Codestruktur - Verständnis der Codebasis

Menu

Entwicklungsworkflow

Issue-Vorlagen

Grundlegender Stil

Namenskonventionen

Kommentare

Umgang mit null

Ausnahmebehandlung

Logging

Lokale Ausführung

Debug-Ausführung

Ausführen von Unit-Tests