Leitfaden für Beiträge

Wir begrüßen Beiträge zum Fess-Projekt! Diese Seite erklärt, wie Sie zu Fess beitragen können, Community-Richtlinien, Schritte zum Erstellen von Pull Requests usw.

Einführung

Fess ist ein Open-Source-Projekt und wächst durch die Beiträge der Community. Jeder kann beitragen, unabhängig vom Erfahrungsniveau in der Programmierung.

Möglichkeiten beizutragen

Sie können auf verschiedene Weise zu Fess beitragen.

Code-Beiträge

Hinzufügen neuer Funktionen
Fehlerbehebungen
Performance-Verbesserungen
Refactoring
Hinzufügen von Tests

Dokumentations-Beiträge

Verbesserung der Benutzerhandbücher
Hinzufügen/Aktualisieren von API-Dokumentation
Erstellen von Tutorials
Übersetzungen

Issue-Berichterstattung

Fehlerberichte
Feature-Anfragen
Fragen oder Vorschläge

Community-Aktivitäten

Diskussionen in GitHub Discussions
Beantworten von Fragen in Foren
Schreiben von Blogbeiträgen oder Tutorials
Präsentationen bei Veranstaltungen

Erster Beitrag

Wenn Sie zum ersten Mal zu Fess beitragen, empfehlen wir die folgenden Schritte.

Schritt 1: Das Projekt verstehen

Überprüfen Sie grundlegende Informationen auf der offiziellen Fess-Website
Verstehen Sie den Entwicklungsüberblick unter Open-Source-Volltextsuche-Server - Fess Entwicklungsübersicht
Lernen Sie die Codestruktur unter Architektur und Codestruktur

Schritt 2: Nach Issues suchen

Suchen Sie auf der GitHub-Issue-Seite nach Issues mit dem Label good first issue.

Diese Issues sind relativ einfache Aufgaben, die für Erstbeiträger geeignet sind.

Schritt 3: Entwicklungsumgebung einrichten

Richten Sie Ihre Entwicklungsumgebung gemäß Einrichten der Entwicklungsumgebung ein.

Schritt 4: Branch erstellen und arbeiten

Erstellen Sie gemäß Entwicklungsworkflow einen Branch und beginnen Sie mit dem Codieren.

Schritt 5: Pull Request erstellen

Committen Sie Ihre Änderungen und erstellen Sie einen Pull Request.

Codierungskonventionen

Fess folgt den folgenden Codierungskonventionen, um konsistenten Code zu pflegen.

Java-Codierungsstil

Grundstil

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

Namenskonventionen

Pakete: Kleinbuchstaben, durch Punkte getrennt (z. B.: org.codelibs.fess)
Klassen: PascalCase (z. B.: SearchService)
Schnittstellen: PascalCase (z. B.: Crawler)
Methoden: camelCase (z. B.: executeSearch)
Variablen: camelCase (z. B.: searchResult)
Konstanten: UPPER_SNAKE_CASE (z. B.: MAX_SEARCH_SIZE)

Kommentare

Javadoc:

Schreiben Sie Javadoc für öffentliche Klassen, Methoden und Felder.

/**
 * Führt die Suche aus.
 *
 * @param query Suchanfrage
 * @return Suchergebnisse
 * @throws SearchException Wenn die Suche fehlschlägt
 */
public SearchResponse executeSearch(String query) throws SearchException {
    // Implementierung
}

Implementierungskommentare:

Fügen Sie für komplexe Logik Kommentare auf Japanisch oder Englisch hinzu.

// Normalisierung der Abfrage (Konvertierung von Vollbreite zu Halbbreite)
String normalizedQuery = QueryNormalizer.normalize(query);

Klassen- und Methodendesign

Prinzip der einzigen Verantwortung: Eine Klasse hat nur eine Verantwortung
Kleine Methoden: Eine Methode macht nur eine Sache
Aussagekräftige Namen: Klassen- und Methodennamen sollten ihre Absicht deutlich machen

Ausnahmebehandlung

// Gutes Beispiel: Angemessene Ausnahmebehandlung
try {
    executeSearch(query);
} catch (IOException e) {
    logger.error("Fehler während der Suche aufgetreten", e);
    throw new SearchException("Suche fehlgeschlagen", e);
}

// Zu vermeidendes Beispiel: Leerer catch-Block
try {
    executeSearch(query);
} catch (IOException e) {
    // Nichts tun
}

Umgang mit null

Vermeiden Sie nach Möglichkeit die Rückgabe von null
Verwendung von Optional wird empfohlen
Kennzeichnen Sie null-Möglichkeit explizit mit @Nullable-Annotation

// Gutes Beispiel
public Optional<User> findUser(String id) {
    return Optional.ofNullable(userMap.get(id));
}

// Verwendungsbeispiel
findUser("123").ifPresent(user -> {
    // Verarbeitung, wenn Benutzer existiert
});

Schreiben von Tests

Schreiben Sie Tests für alle öffentlichen Methoden
Testmethodennamen beginnen mit test
Verwenden Sie das Given-When-Then-Muster

@Test
public void testSearch() {
    // Given: Testvoraussetzungen
    SearchService service = new SearchService();
    String query = "test";

    // When: Ausführung des Testobjekts
    SearchResponse response = service.search(query);

    // Then: Überprüfung der Ergebnisse
    assertNotNull(response);
    assertEquals(10, response.getDocuments().size());
}

Code-Review-Richtlinien

Pull-Request-Review-Prozess

Automatische Überprüfung: CI führt automatisch Builds und Tests aus
Code-Review: Betreuer überprüfen den Code
Feedback: Änderungsanfragen bei Bedarf
Genehmigung: Review wird genehmigt
Merge: Betreuer merged in den main-Branch

Review-Aspekte

Im Review werden folgende Punkte überprüft:

Funktionalität

Erfüllt es die Anforderungen
Funktioniert es wie beabsichtigt
Werden Randfälle berücksichtigt

Code-Qualität

Entspricht es den Codierungskonventionen
Ist der Code lesbar und wartbar
Ist die Abstraktion angemessen

Tests

Sind ausreichende Tests geschrieben
Bestehen die Tests
Führen die Tests sinnvolle Überprüfungen durch

Performance

Gibt es Auswirkungen auf die Performance
Ist die Ressourcennutzung angemessen

Sicherheit

Gibt es Sicherheitsprobleme
Ist die Eingabevalidierung angemessen

Dokumentation

Ist die erforderliche Dokumentation aktualisiert
Ist Javadoc angemessen geschrieben

Antworten auf Review-Kommentare

Reagieren Sie auf Review-Kommentare zeitnah und höflich.

Wenn Änderungen erforderlich sind:

Vielen Dank für Ihren Hinweis. Ich habe es korrigiert.
[Kurze Beschreibung der Änderungen]

Wenn Diskussion erforderlich ist:

Vielen Dank für Ihre Meinung.
Aus Gründen von XX habe ich die aktuelle Implementierung gewählt,
wäre die Implementierung von YY besser?

Best Practices für Pull Requests

Größe der PR

Erstellen Sie kleine, leicht zu überprüfende PRs
Eine PR sollte eine logische Änderung enthalten
Teilen Sie große Änderungen in mehrere PRs auf

PR-Titel

Geben Sie einen klaren und beschreibenden Titel an:

feat: Filterfunktion für Suchergebnisse hinzugefügt
fix: Timeout-Problem des Crawlers behoben
docs: API-Dokumentation aktualisiert

PR-Beschreibung

Fügen Sie folgende Informationen hinzu:

Änderungsinhalt: Was wurde geändert
Grund: Warum diese Änderung notwendig ist
Testmethode: Wie wurde es getestet
Screenshots: Bei UI-Änderungen
Zugehöriges Issue: Issue-Nummer (z. B.: Closes #123)

## Änderungsinhalt
Funktion zum Filtern von Suchergebnissen nach Dateityp hinzugefügt.

## Grund
Viele Benutzeranfragen nach "Suche nur nach bestimmten Dateitypen".

## Testmethode
1. Dateityp-Filter auf der Suchseite auswählen
2. Suche ausführen
3. Überprüfen, dass nur Ergebnisse des ausgewählten Dateityps angezeigt werden

## Zugehöriges Issue
Closes #123

Commit-Nachrichten

Schreiben Sie klare und beschreibende Commit-Nachrichten:

<type>: <subject>

<body>

<footer>

Beispiel:

feat: Suchfilterfunktion hinzugefügt

Benutzer können jetzt Suchergebnisse nach Dateityp filtern.

- Filter-UI hinzugefügt
- Backend-Filterverarbeitung implementiert
- Tests hinzugefügt

Closes #123

Verwendung von Draft-PRs

Erstellen Sie PRs, an denen Sie noch arbeiten, als Draft-PR und ändern Sie sie zu „Ready for review“, wenn sie fertig sind.

1. Wählen Sie beim Erstellen der PR "Create draft pull request"
2. Klicken Sie auf "Ready for review", wenn die Arbeit abgeschlossen ist

Community-Richtlinien

Verhaltenskodex

Die Fess-Community hält sich an folgenden Verhaltenskodex:

Respektvoll sein: Respektieren Sie alle Menschen
Kooperativ sein: Geben Sie konstruktives Feedback
Offen sein: Begrüßen Sie unterschiedliche Perspektiven und Erfahrungen
Höflich sein: Verwenden Sie höfliche Sprache

Kommunikation

Wo Sie Fragen stellen können:

GitHub Discussions: Allgemeine Fragen und Diskussionen
Issue-Tracker: Fehlerberichte und Feature-Anfragen
Fess-Forum: Japanisches Forum

Wie man Fragen stellt:

Fragen Sie konkret
Erklären Sie, was Sie versucht haben
Fügen Sie Fehlermeldungen oder Logs hinzu
Geben Sie Umgebungsinformationen an (OS, Java-Version usw.)

Wie man antwortet:

Höflich und freundlich
Geben Sie konkrete Lösungen an
Bieten Sie Links zu Referenzmaterialien

Dankbarkeit ausdrücken

Wir drücken Dankbarkeit für Beiträge aus. Auch kleine Beiträge sind für das Projekt wertvoll.

Häufig gestellte Fragen

F: Können auch Anfänger beitragen?

A: Ja, herzlich willkommen! Wir empfehlen, mit Issues zu beginnen, die das Label good first issue haben. Auch die Verbesserung der Dokumentation ist ein für Anfänger geeigneter Beitrag.

F: Wie schnell werden Pull Requests überprüft?

A: Normalerweise innerhalb weniger Tage. Dies kann jedoch je nach Zeitplan der Betreuer variieren.

F: Was passiert, wenn ein Pull Request abgelehnt wird?

A: Überprüfen Sie den Grund für die Ablehnung und Sie können ihn nach Änderungen erneut einreichen. Wenn Sie unsicher sind, fragen Sie gerne nach.

F: Was passiert, wenn ich gegen Codierungskonventionen verstoße?

A: Es wird im Review darauf hingewiesen, also ist es kein Problem, wenn Sie es korrigieren. Sie können es vorab überprüfen, indem Sie Checkstyle ausführen.

F: Was ist, wenn ich eine große Funktion hinzufügen möchte?

A: Wir empfehlen, zuerst ein Issue zu erstellen und den Vorschlag zu diskutieren. Durch vorherige Einigung können Sie verschwenderische Arbeit vermeiden.

F: Darf ich auf Japanisch fragen?

A: Ja, sowohl Japanisch als auch Englisch sind in Ordnung. Fess ist ein Projekt aus Japan, daher gibt es auch gute japanische Unterstützung.

Leitfaden nach Art des Beitrags

Verbesserung der Dokumentation

Forken Sie das Dokumentations-Repository:

git clone https://github.com/codelibs/fess-docs.git

Nehmen Sie Änderungen vor
Erstellen Sie einen Pull Request

Fehlerbericht

Suchen Sie nach vorhandenen Issues, um Duplikate zu vermeiden
Erstellen Sie ein neues Issue
Fügen Sie folgende Informationen hinzu:
- Fehlerbeschreibung
- Schritte zur Reproduktion
- Erwartetes Verhalten
- Tatsächliches Verhalten
- Umgebungsinformationen

Feature-Anfrage

Erstellen Sie ein Issue
Erklären Sie Folgendes:
- Beschreibung der Funktion
- Hintergrund und Motivation
- Vorgeschlagene Implementierungsmethode (optional)

Code-Review

Die Überprüfung der Pull Requests anderer Personen ist ebenfalls ein Beitrag:

Finden Sie eine interessante PR
Überprüfen Sie den Code
Geben Sie konstruktives Feedback

Richten Sie Ihre Entwicklungsumgebung mit Einrichten der Entwicklungsumgebung ein
Überprüfen Sie den Entwicklungsablauf mit Entwicklungsworkflow
Suchen Sie nach Issues auf GitHub

Referenzmaterialien

Community-Ressourcen

GitHub: codelibs/fess
Discussions: GitHub Discussions
Forum: Fess-Forum
Twitter: @codelibs
Website: fess.codelibs.org

Menu