Contribuer

Nous accueillons les contributions à ce projet ! Ce guide vous aidera à démarrer.

Comment contribuer

1. Fork le projet

Créez un fork du dépôt sur GitHub :

# Via l'interface GitHub
# Cliquez sur "Fork" en haut à droite

2. Cloner votre fork

git clone https://github.com/votre-username/fasoarzeka.git
cd fasoarzeka

3. Créer une branche

git checkout -b feature/ma-nouvelle-fonctionnalite

Utilisez des noms de branches descriptifs :

  • feature/nom : Nouvelle fonctionnalité

  • fix/nom : Correction de bug

  • docs/nom : Documentation

  • refactor/nom : Refactoring

4. Faire vos modifications

Suivez les Directives de code ci-dessous.

5. Tester vos modifications

# Installer les dépendances de développement
pip install -r requirements-dev.txt

# Exécuter les tests
pytest

# Vérifier le coverage
pytest --cov=fasoarzeka

# Linter
flake8 src/
black src/
mypy src/

6. Commiter vos changements

git add .
git commit -m "feat: ajouter nouvelle fonctionnalité"

Utilisez des messages de commit conventionnels :

  • feat: : Nouvelle fonctionnalité

  • fix: : Correction de bug

  • docs: : Documentation

  • style: : Formatting, pas de changement de code

  • refactor: : Refactoring

  • test: : Ajout de tests

  • chore: : Maintenance

7. Pousser vers GitHub

git push origin feature/ma-nouvelle-fonctionnalite

8. Créer une Pull Request

Allez sur GitHub et créez une Pull Request depuis votre branche.

Directives de code

Style de code

Nous suivons les conventions Python standard :

  • PEP 8 : Guide de style Python

  • PEP 484 : Type Hints

  • Black : Formatage automatique

# ✅ BON
def authenticate(username: str, password: str) -> Dict[str, Any]:
    """
    Authentifie l'utilisateur.

    Args:
        username: Nom d'utilisateur
        password: Mot de passe

    Returns:
        Dictionnaire d'authentification
    """
    # Code...

# ❌ MAUVAIS
def auth(u, p):
    # Code sans documentation ni types...

Docstrings

Utilisez le format Google docstring :

def my_function(param1: str, param2: int) -> bool:
    """
    Description courte de la fonction.

    Description plus longue si nécessaire, expliquant
    le fonctionnement en détail.

    Args:
        param1: Description du paramètre 1
        param2: Description du paramètre 2

    Returns:
        Description de la valeur de retour

    Raises:
        ValueError: Quand param2 est négatif

    Example:
        >>> my_function("test", 42)
        True
    """
    if param2 < 0:
        raise ValueError("param2 must be positive")
    return True

Type hints

Utilisez toujours les type hints :

from typing import Dict, List, Optional, Any

def process_payment(
    amount: int,
    merchant_id: str,
    additional_info: Dict[str, str]
) -> Dict[str, Any]:
    ...

Tests

Écrivez des tests pour toutes les nouvelles fonctionnalités :

import pytest
from fasoarzeka import ArzekaPayment

class TestArzekaPayment:
    def test_authenticate_success(self):
        """Test d'authentification réussie"""
        client = ArzekaPayment()
        auth = client.authenticate("user", "pass")

        assert 'access_token' in auth
        assert auth['token_type'] == 'Bearer'

    def test_authenticate_failure(self):
        """Test d'authentification échouée"""
        client = ArzekaPayment()

        with pytest.raises(ArzekaAuthenticationError):
            client.authenticate("wrong", "credentials")

Documentation

Documentez toutes les fonctions publiques :

def initiate_payment(self, amount: int, ...) -> Dict[str, Any]:
    """
    Initie un nouveau paiement.

    Cette méthode crée une transaction de paiement et retourne
    une URL vers laquelle rediriger l'utilisateur.

    Args:
        amount: Montant en FCFA (minimum 100)
        ...

    Returns:
        Dictionnaire contenant:
        - mappedOrderId: ID de la commande
        - url: URL de redirection
        - qrcode: QR code de paiement

    Raises:
        ArzekaValidationError: Si les données sont invalides
        ArzekaAPIError: Si l'API retourne une erreur

    Example:
        >>> response = client.initiate_payment(
        ...     amount=1000,
        ...     merchant_id="MERCHANT_123"
        ... )
    """

Domaines de contribution

Code

  • Nouvelles fonctionnalités

  • Corrections de bugs

  • Améliorations de performance

  • Refactoring

Documentation

  • Corrections de typos

  • Amélioration des exemples

  • Traductions

  • Tutoriels

Tests

  • Nouveaux tests

  • Amélioration de la couverture

  • Tests d’intégration

Processus de review

Les Pull Requests seront reviewées selon ces critères :

✅ Code

  • [ ] Suit le style PEP 8

  • [ ] Type hints inclus

  • [ ] Docstrings présents

  • [ ] Pas de code dupliqué

✅ Tests

  • [ ] Tests unitaires ajoutés

  • [ ] Tests passent

  • [ ] Couverture maintenue/améliorée

✅ Documentation

  • [ ] Documentation ajoutée/mise à jour

  • [ ] Exemples inclus

  • [ ] Changelog mis à jour

✅ Commit

  • [ ] Messages de commit clairs

  • [ ] Commits atomiques

  • [ ] Branche à jour avec main

Ressources

Questions ?

Si vous avez des questions, n’hésitez pas à :

  • Ouvrir une issue sur GitHub

  • Contacter les mainteneurs

Merci de contribuer ! 🎉