Guide de contribution

Nous accueillons les contributions au projet Fess ! Cette page explique comment contribuer à Fess, les directives communautaires, les procédures de création de pull requests, etc.

Introduction

Fess est un projet open source, qui se développe grâce aux contributions de la communauté. Tout le monde peut contribuer, quel que soit son niveau d’expérience en programmation.

Méthodes de contribution

Vous pouvez contribuer à Fess de diverses manières.

Contributions de code

Ajout de nouvelles fonctionnalités
Correction de bugs
Amélioration des performances
Refactoring
Ajout de tests

Contributions à la documentation

Amélioration des manuels utilisateur
Ajout et mise à jour de la documentation API
Création de tutoriels
Traduction

Rapport de problèmes

Rapports de bugs
Demandes de fonctionnalités
Questions et suggestions

Activités communautaires

Discussions sur GitHub Discussions
Répondre aux questions sur le forum
Rédaction d’articles de blog et de tutoriels
Présentations lors d’événements

Première contribution

si vous contribuez à Fess pour la première fois, nous vous recommandons les étapes suivantes.

Étape 1 : Comprendre le projet

Consultez les informations de base sur le site officiel de Fess
Comprenez l’aperçu du développement dans serveur de recherche plein texte open source - Aperçu du développement Fess
Apprenez la structure du code dans Architecture et structure du code

Étape 2 : Trouver un problème

sur la page des problèmes GitHub, recherchez les problèmes avec l’étiquette good first issue.

Ces problèmes sont des tâches relativement simples adaptées aux nouveaux contributeurs.

Étape 3 : Configurer l’environnement de développement

Configurez l’environnement de développement en suivant Configuration de l’environnement de développement.

Étape 4 : Créer une branche et travailler

Créez une branche et commencez le codage en suivant Flux de travail de développement.

Étape 5 : Créer une pull request

Commitez les modifications et créez une pull request.

Conventions de codage

Fess suit les conventions de codage suivantes pour maintenir un code cohérent.

style de codage Java

style de base

Indentation : 4 espaces
Code de fin de ligne : LF (style Unix)
Encodage : UTF-8
Longueur de ligne : 120 caractères maximum recommandé

Conventions de nommage

Packages : minuscules, séparés par des points (ex : org.codelibs.fess)
Classes : PascalCase (ex : searchservice)
Interfaces : PascalCase (ex : Crawler)
Méthodes : camelCase (ex : executesearch)
Variables : camelCase (ex : searchResult)
Constantes : UPPER_sNAKE_CAsE (ex : MAX_sEARCH_sIZE)

Commentaires

Javadoc:

Écrivez Javadoc pour les classes, méthodes et champs publics.

/**
 * Exécute une recherche.
 *
 * @param query Requête de recherche
 * @return Résultats de recherche
 * @throws searchException En cas d'échec de la recherche
 */
public searchResponse executesearch(string query) throws searchException {
    // Implémentation
}

Commentaires d’implémentation:

Ajoutez des commentaires en japonais ou en anglais pour une logique complexe.

// Normalisation de la requête (conversion pleine chasse en demi-chasse)
string normalizedQuery = QueryNormalizer.normalize(query);

Conception des classes et méthodes

Principe de responsabilité unique : Une classe n’a qu’une seule responsabilité
Petites méthodes : Une méthode ne fait qu’une seule chose
Noms significatifs : Les noms de classes et de méthodes doivent être clairs dans leur intention

Gestion des exceptions

// Bon exemple : Gestion appropriée des exceptions
try {
    executesearch(query);
} catch (IOException e) {
    logger.error("Une erreur s'est produite lors de la recherche", e);
    throw new searchException("L'exécution de la recherche a échoué", e);
}

// Exemple à éviter : Bloc catch vide
try {
    executesearch(query);
} catch (IOException e) {
    // Ne fait rien
}

Gestion de null

Ne pas retourner null dans la mesure du possible
Utilisation d”Optional recommandée
Indiquer explicitement la possibilité de null avec l’annotation @Nullable

// Bon exemple
public Optional<User> findUser(string id) {
    return Optional.ofNullable(userMap.get(id));
}

// Exemple d'utilisation
findUser("123").ifPresent(user -> {
    // Traitement si l'utilisateur existe
});

Rédaction de tests

Écrire des tests pour toutes les méthodes publiques
Les noms de méthodes de test commencent par test
Utiliser le modèle Given-When-Then

@Test
public void testsearch() {
    // Given: Conditions préalables du test
    searchservice service = new searchservice();
    string query = "test";

    // When: Exécution du sujet du test
    searchResponse response = service.search(query);

    // Then: Vérification des résultats
    assertNotNull(response);
    assertEquals(10, response.getDocuments().size());
}

Directives de revue de code

Processus de revue des pull requests

Vérification automatique : CI exécute automatiquement la compilation et les tests
Revue de code : Les mainteneurs examinent le code
Retour d’information : Demandes de modifications si nécessaire
Approbation : La revue est approuvée
Fusion : Les mainteneurs fusionnent dans la branche main

Points de revue

Les revues vérifient les points suivants :

Fonctionnalité

Répond-elle aux exigences
Fonctionne-t-elle comme prévu
Les cas limites sont-ils pris en compte

Qualité du code

suit-elle les conventions de codage
Le code est-il lisible et maintenable
Les abstractions sont-elles appropriées

Tests

suffisamment de tests sont-ils écrits
Les tests passent-ils
Les tests font-ils des vérifications significatives

Performance

Y a-t-il un impact sur les performances
L’utilisation des ressources est-elle appropriée

sécurité

Y a-t-il des problèmes de sécurité
La validation des entrées est-elle appropriée

Documentation

La documentation nécessaire est-elle mise à jour
Javadoc est-elle écrite de manière appropriée

Réponse aux commentaires de revue

Répondez rapidement et poliment aux commentaires de revue.

En cas de modifications nécessaires:

Merci pour votre remarque. J'ai effectué les corrections.
[Brève explication des modifications]

En cas de discussion nécessaire:

Merci pour votre avis.
J'ai utilisé l'implémentation actuelle pour la raison XX,
mais pensez-vous qu'une implémentation YY serait meilleure ?

Meilleures pratiques des pull requests

Taille de la PR

Viser des PR petites et faciles à examiner
Inclure un seul changement logique par PR
Diviser les grands changements en plusieurs PR

Titre de la PR

Donnez un titre clair et descriptif :

feat: Ajouter une fonctionnalité de filtrage des résultats de recherche
fix: Corriger le problème de timeout du crawler
docs: Mettre à jour la documentation API

Description de la PR

Incluez les informations suivantes :

Modifications : Ce qui a été modifié
Raison : Pourquoi ce changement est nécessaire
Méthode de test : Comment cela a été testé
Captures d’écran : En cas de modifications de l’interface utilisateur
Problème connexe : Numéro du problème (ex : Closes #123)

## Modifications
Ajout d'une fonctionnalité permettant de filtrer les résultats de recherche par type de fichier.

## Raison
De nombreuses demandes d'utilisateurs souhaitant "rechercher uniquement un type de fichier spécifique".

## Méthode de test
1. sélectionner le filtre de type de fichier sur l'écran de recherche
2. Exécuter la recherche
3. Vérifier que seuls les résultats du type de fichier sélectionné sont affichés

## Problème connexe
Closes #123

Messages de commit

Écrivez des messages de commit clairs et descriptifs :

<type>: <sujet>

<corps>

<pied de page>

Exemple:

feat: Ajouter une fonctionnalité de filtre de recherche

Permet aux utilisateurs de filtrer les résultats de recherche par type de fichier.

- Ajout de l'interface utilisateur de filtre
- Implémentation du traitement de filtre backend
- Ajout de tests

Closes #123

Utilisation des Draft PR

Créez des PR en cours de travail comme Draft PR, et changez en Ready for review une fois terminé.

1. sélectionner « Create draft pull request » lors de la création de PR
2. Cliquer sur « Ready for review » une fois le travail terminé

Directives de la communauté

Code de conduite

La communauté Fess respecte le code de conduite suivant :

Être respectueux : Respecter toutes les personnes
Être coopératif : Fournir des retours constructifs
Être ouvert : Accueillir différentes perspectives et expériences
Être poli : s’efforcer d’utiliser un langage courtois

Communication

Où poser des questions:

GitHub Discussions : Questions générales et discussions
suivi des problèmes : Rapports de bugs et demandes de fonctionnalités
Forum Fess : Forum en japonais

Comment poser des questions:

Poser des questions spécifiques
Expliquer ce qui a été essayé
Inclure les messages d’erreur et les journaux
Indiquer les informations d’environnement (Os, version Java, etc.)

Comment répondre:

Poliment et gentiment
Proposer des solutions concrètes
Fournir des liens vers des ressources de référence

Expression de gratitude

Exprimez votre gratitude pour les contributions. Même les petites contributions ont de la valeur pour le projet.

R: Oui, avec plaisir ! Nous vous recommandons de commencer par les problèmes avec l’étiquette good first issue. L’amélioration de la documentation est également une contribution adaptée aux débutants.

Q: Dans combien de temps les pull requests sont-elles examinées ?

R: Normalement, elles sont examinées dans les quelques jours. Cependant, cela peut varier en fonction du calendrier des mainteneurs.

Q: Que se passe-t-il si une pull request est rejetée ?

R: Vérifiez la raison du rejet et, si nécessaire, corrigez et soumettez à nouveau. si vous avez des questions, n’hésitez pas à les poser.

Q: Que faire en cas de violation des conventions de codage ?

R: Elles seront signalées lors de la revue, donc les corriger ne posera pas de problème. Vous pouvez vérifier à l’avance en exécutant Checkstyle.

Q: Comment ajouter une grande fonctionnalité ?

R: Nous vous recommandons de créer d’abord un problème et de discuter de la proposition. Obtenir un accord préalable permet d’éviter un travail inutile.

Q: Puis-je poser des questions en japonais ?

R: Oui, le japonais et l’anglais sont acceptés. Fess est un projet d’origine japonaise, donc le support en japonais est également complet.

Guides par type de contribution

Amélioration de la documentation

Forkez le dépôt de documentation :

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

Apportez des modifications
Créez une pull request

Rapport de bugs

Recherchez les problèmes existants pour vérifier les doublons
Créez un nouveau problème
Incluez les informations suivantes :
- Description du bug
- Étapes de reproduction
- Comportement attendu
- Comportement réel
- Informations sur l’environnement