Skip to content

contributing.md

Latest commit

 

History

History
284 lines (206 loc) · 6.84 KB

contributing.md

File metadata and controls

284 lines (206 loc) · 6.84 KB
Raw

Contributing to Velocity Search Engine

Merci de contribuer au Velocity Search Engine ! Ce guide vous aidera à comprendre comment participer au développement.

🎯 Comment Contribuer

Types de Contributions

  • 🐛 Bug Reports : Signaler des problèmes
  • ✨ Feature Requests : Proposer de nouvelles fonctionnalités
  • 📖 Documentation : Améliorer la documentation
  • 🔧 Code : Corrections et nouvelles fonctionnalités
  • 🧪 Tests : Ajouter ou améliorer les tests
  • ⚡ Performance : Optimisations et benchmarks

🚀 Démarrage Rapide

1. Setup Environnement Développement

# Fork et clone le repo
git clone https://github.com/votre-username/velocity-search.git
cd velocity-search

# Setup environnement virtuel
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate     # Windows

# Installation développement
make install-dev

2. Vérification de l'Installation

# Tests complets
make test

# Benchmarks
make benchmark

# Qualité code
make lint
make format

📋 Workflow de Développement

1. Issues et Planification

  1. Recherchez les issues existantes avant d'en créer une nouvelle
  2. Utilisez les templates pour bug reports et feature requests
  3. Assignez-vous l'issue si vous comptez la traiter
  4. Discutez des grandes fonctionnalités avant implémentation

2. Branches et Commits

# Créer une branche feature
git checkout -b feature/nom-de-la-feature

# Créer une branche bugfix  
git checkout -b bugfix/description-du-bug

# Commits conventionnels
git commit -m "feat(indexer): add BM25 algorithm support"
git commit -m "fix(preprocessor): handle empty documents"
git commit -m "docs(api): update core module documentation"

3. Pull Requests

  1. Testez votre code avec make test
  2. Benchmarkez si pertinent avec make benchmark
  3. Documentez les changements dans la PR
  4. Référencez les issues concernées
  5. Demandez une review

🧪 Standards de Qualité

Tests

  • Couverture minimum : 80%
  • Tests unitaires : Chaque fonction publique
  • Tests d'intégration : Workflows complets
  • Benchmarks : Fonctionnalités critiques
# Exécuter les tests
pytest tests/ -v

# Avec couverture
pytest tests/ --cov=src --cov-report=html

# Benchmarks uniquement  
pytest tests/benchmarks/ -v

Style de Code

  • Formatter : Black avec ligne 88 caractères
  • Linter : Flake8 + pylint
  • Type hints : Obligatoires pour fonctions publiques
  • Docstrings : Format Google pour toutes les classes/fonctions
# Auto-formatting
make format

# Vérification style
make lint

# Type checking
make type-check

Documentation

  • Docstrings : Google format
  • Type hints : Complets et précis
  • Examples : Code examples dans la doc
  • API docs : Mise à jour automatique
def search(self, query: str, limit: int = 10) -> List[SearchResult]:
    """Recherche des documents pertinents.
    
    Args:
        query: Requête de recherche utilisateur
        limit: Nombre maximum de résultats à retourner
        
    Returns:
        Liste des résultats classés par pertinence
        
    Raises:
        ValueError: Si la requête est vide
        
    Example:
        >>> engine = VelocitySearch()
        >>> results = engine.search("Python programming")
        >>> print(f"Found {len(results)} results")
    """

🏗️ Architecture et Design

Principes

  1. Modularité : Séparation claire des responsabilités
  2. Performance : Optimisé pour la vitesse et la mémoire
  3. Extensibilité : Faciliter l'ajout de nouvelles fonctionnalités
  4. Testabilité : Code facile à tester et déboguer

Ajout de Nouveaux Modules

# Structure standard d'un module
src/nouveau_module/
├── __init__.py          # Exports publics
├── core.py             # Logique principale  
├── models.py           # Classes de données
├── utils.py            # Utilitaires spécifiques
└── exceptions.py       # Exceptions personnalisées

Performance

  • Profiling obligatoire pour optimisations
  • Benchmarks avant/après pour changements critiques
  • Complexité documentée pour algorithmes
  • Memory leaks vérifiés avec outils appropriés

🐛 Reporting de Bugs

Template Bug Report

**Description**
Description claire du bug

**Reproduction**
Étapes pour reproduire le comportement:
1. Allez à '...'
2. Cliquez sur '....'
3. Défilez vers '....'
4. Voir erreur

**Comportement Attendu**
Description claire de ce qui devrait se passer

**Screenshots/Logs**
Si applicable, ajoutez des captures d'écran ou logs

**Environment:**
- OS: [e.g. Ubuntu 20.04]
- Python: [e.g. 3.9.7]
- Version: [e.g. 1.2.3]

✨ Feature Requests

Template Feature Request

**Problème à Résoudre**
Description claire du problème que cette feature résoudrait

**Solution Proposée**
Description claire de la solution souhaitée

**Alternatives Considérées**
Description des alternatives que vous avez considérées

**Impact**
- Performance: Impact estimé sur les performances
- Breaking changes: Changements incompatibles
- Dependencies: Nouvelles dépendances requises

📊 Benchmarking

Ajout de Benchmarks

# tests/benchmarks/benchmark_nouveau_module.py
import pytest
from src.nouveau_module import NouvelleFonction

class TestNouveauModuleBenchmarks:
    def setup_method(self):
        self.function = NouvelleFonction()
        
    @pytest.mark.benchmark(group="nouveau_module")
    def test_performance_fonction(self, benchmark):
        """Benchmark de la nouvelle fonction."""
        result = benchmark(self.function.execute, "test_data")
        assert result is not None

Critères Performance

  • Indexation : < 1s pour 1000 documents
  • Recherche : < 100ms pour requête simple
  • Memory : < 500MB pour 100k documents
  • Throughput : > 1000 requêtes/seconde

🎯 Release Process

Versioning

  • Semantic Versioning (MAJOR.MINOR.PATCH)
  • Breaking changes : MAJOR increment
  • New features : MINOR increment
  • Bug fixes : PATCH increment

Release Checklist

  • Tests passent (29/29)
  • Benchmarks stables (12/12)
  • Documentation mise à jour
  • CHANGELOG.md mis à jour
  • Version bumped
  • Tag créé
  • Release notes rédigées

🏆 Reconnaissance

Les contributeurs sont reconnus dans :

  • README.md : Section contributeurs
  • CHANGELOG.md : Crédits par version
  • Release notes : Mentions spéciales
  • Hall of fame : Top contributeurs

📞 Support

  • Issues GitHub : Pour bugs et features
  • Discussions : Pour questions générales
  • Email mainteneurs : Pour questions privées
  • Documentation : Guide complet dans /docs

Merci de rendre Velocity Search Engine encore meilleur ! 🚀