🚀 Contributing to EasySwitch¶

Thank you for your interest in contributing to EasySwitch! This guide will help you contribute effectively while maintaining our quality standards.

🔍 Prerequisites¶

Python 3.10+
UV (recommended) or pip
Basic knowledge of payment APIs
Familiarity with async testing

💻 Local Setup¶

1. Fork the Repository¶

Click "Fork" at the top-right of the project's GitHub page.

2. Clone the Project¶

git clone https://github.com/your-username/easyswitch.git
cd easyswitch

3. Set Up the Environment¶

With UV (recommended):

# Install UV
pip install uv

# Create virtual environment
uv venv

# Activate environment
source venv/bin/activate  # Linux/Mac
# OR
.\venv\Scripts\activate   # Windows

# Install dependencies
uv pip install -e .

With standard pip:

python -m venv venv
source venv/bin/activate
pip install -e .

🔄 Contribution Workflow¶

Create a Branch
```
git checkout -b feat/new-feature
```
Implement Your Changes
Follow code conventions
Add relevant tests

Verify Code Quality

uv run lint   # Style check
uv run test   # Run tests

Push Changes
```
git push origin feat/new-feature
```
Open a Pull Request
Complete the PR template
Clearly describe your changes
Reference related issues

✨ Code Conventions¶

General Structure¶

Typing: Use type annotations everywhere
Async: Prefer async/await for I/O operations
Exceptions: Use the project's custom exceptions

Style Guide¶

Naming:
Variables/functions: snake_case
Classes: PascalCase
Constants: UPPER_CASE

Docstrings: Follow Google Style

def send_payment(amount: float) -> bool:
    """Sends payment to the aggregator.

    Args:
        amount: Amount to send (in XOF)

    Returns:
        bool: True if payment succeeded
    """

Validation¶

Use validators from easyswitch.utils.validators
Always validate API inputs

🧪 Testing & Quality¶

Running Tests¶

uv run test  # All tests
uv run test -k "test_payment"  # Specific tests

Code Coverage¶

uv run coverage

Best Practices¶

1 test per feature
Isolated, idempotent tests
Mock external APIs

🐛 Issue Management¶

Reporting Bugs¶

Check for existing issues
Use the "Bug Report" template
Include:
Environment (Python, OS)
Reproduction steps
Relevant logs/errors

Feature Proposals¶

Use the "Feature Request" template
Describe:
Use case
Expected impact
API sketch if applicable

🤝 Code of Conduct¶

We adhere to the Contributor Covenant Code of Conduct. By participating: - Be kind and open-minded - Accept constructive feedback - Prioritize collaboration

🎉 First-Time Contributor?¶

Check out these labeled issues: - good first issue for simple contributions - help wanted for more challenging tasks

Thank you for helping make EasySwitch even better! 💪