Comment ajouter un Nouveau Problème

[Hugues-DTANKOUO]

Comment ajouter un Nouveau Problème

Vue d'ensemble

Ce guide explique le processus et les exigences pour ajouter un nouveau problème de programmation à notre application Problems. Les nouveaux problèmes aident à enrichir notre collection et offrent plus d'opportunités d'apprentissage aux utilisateurs.

Note importante : Bien que cette documentation soit disponible en français, le code source, les commentaires et les docstrings doivent être écrits en anglais pour maintenir la cohérence du projet. Si vous avez des difficultés avec l'anglais, n'hésitez pas à utiliser un service de traduction ou à demander de l'aide. L'équipe peut vous assister pour la révision linguistique si nécessaire.

Exigences pour la contribution de problèmes

1. Sélection du problème

Lors du choix d'un problème à ajouter :

• Assurez-vous qu'il ne duplique pas un problème existant
• Sélectionnez un niveau de difficulté approprié (Easy, Medium, Hard)
• Choisissez des problèmes à valeur éducative qui enseignent des algorithmes spécifiques ou des concepts de programmation
• Considérez les aspects d'efficacité computationnelle qui pourraient être testés

2. Structure du problème

Chaque nouveau problème nécessite les fichiers suivants :

src/problems/votre_probleme.py                     # Implémentation de la fonction principale
src/problems/inside_test/votre_probleme_test.py    # Cas de tests internes
tests/test_votre_probleme.py                       # Tests externes validant les tests internes

Optionnel (si nécessaire) :

src/problems/inside_test/data/votre_probleme/      # Fichiers de données de test si requis

3. Exigences d'implémentation

Fichier de fonction principale (votre_probleme.py)

"""
.## Level: Easy/Medium/Hard

[Description détaillée du problème avec informations de contexte]

.## Example:

[Montrer des exemples d'utilisation avec entrée/sortie]

>votre_probleme exemple_entree
sortie_attendue

"""

# Importer les bibliothèques nécessaires ici

def votre_probleme(param1: Type, param2: Type) -> TypeRetour:
    """
    Clear description of what the function does.

    :param param1: Description of first parameter
    :param param2: Description of second parameter
    :return: Description of the return value
    """
    # Ceci doit être un modèle que les utilisateurs implémenteront
    return ...  # type: ignore[return-value]

Tests internes (inside_test/votre_probleme_test.py)

from typing import Callable

from problems.inside_test.util import async_timeout


async def votre_probleme_test_case_1(func: Callable[[Type], TypeRetour]) -> None:
    """
    GIVEN [description of test conditions]
    WHEN the function is called
    THEN it should [expected outcome]
    """
    _functional_votre_probleme = async_timeout(100)(func)
    
    # Implémentation du test
    result = await _functional_votre_probleme(entree_test)
    assert result == sortie_attendue, "Error message"
    
    # Ajoutez plus d'assertions si nécessaire

Créez plusieurs fonctions de test pour différents cas de test.

Tests externes (test_votre_probleme.py)

import pytest

from problems.inside_test import votre_probleme_test
from problems.votre_probleme import votre_probleme


def correct_votre_probleme(param1: Type, param2: Type) -> TypeRetour:
    """
    A correct implementation of the problem for testing.
    """
    # Implémentez la solution correcte ici
    

async def test_test_case_with_base_function_then_error() -> None:
    """
    GIVEN the test case and base function
    WHEN the test case is run
    THEN an AssertionError should be raised
    """
    with pytest.raises(AssertionError):
        await votre_probleme_test.votre_probleme_test_case_1(votre_probleme)


async def test_test_case_with_correct_function_then_success() -> None:
    """
    GIVEN the test case and correct function
    WHEN the test case is run
    THEN any error should not be raised
    """
    await votre_probleme_test.votre_probleme_test_case_1(correct_votre_probleme)

4. Mises à jour des fichiers existants

Les fichiers suivants doivent être mis à jour :

1. src/problems/interface.py : Ajoutez votre problème à PROBLEMS_LIST

   PROBLEMS_LIST = ["anagram", "palindrome", "knapsack", "nqueens", "votre_probleme"]

2. problems.md : Ajoutez votre problème à la liste avec une description

   ### <u><a> [5. 🟢/🟡/🔴 **Votre Problème** - *Easy/Medium/Hard*](/src/problems/votre_probleme.py) </a></u>
   <br>
   
   Brève description de votre problème et de son importance.
   
   **Key Concepts:**
   - Concept 1
   - Concept 2
   - Concept 3
   
   **Example:**
   ```python
   > votre_probleme(exemple_entree)
   sortie_attendue

3. CHANGELOG.md : Ajoutez votre problème à la section "Next Version"

   ## Next Version
   
   ### 🚀 New Features:
   
   - Added [Votre Problème](/src/problems/votre_probleme.py) problem (Easy/Medium/Hard)

5. Exigences de tests

• Assurez-vous que tous les tests passent avec l'implémentation correcte
• Incluez des tests de timeout pour les problèmes critiques en termes de performance
• Vérifiez que les tests de la fonction de base échouent correctement
• Couvrez les cas limites et les entrées inattendues

Processus de soumission

1. Faites un fork du dépôt
2. Créez une branche de fonctionnalité (feature/votre_probleme)
3. Implémentez les fichiers requis
4. Exécutez les tests et assurez-vous qu'ils passent
5. Soumettez une pull request avec une description claire

Critères de révision

Votre soumission de problème sera examinée pour :

• Qualité du code et respect des standards du projet
• Couverture et robustesse des tests
• Valeur éducative
• Clarté de la description du problème
• Catégorisation appropriée de la difficulté

Exemples

Pour référence, examinez ces problèmes existants :

• anagram.py - Exemple d'un problème Easy
• knapsack.py - Exemple d'un problème Medium
• nqueens.py - Exemple d'un problème Hard

---

Merci de contribuer à notre collection de problèmes ! Votre contribution aide les autres à apprendre et à améliorer leurs compétences en programmation.