Contributing

Thank you for your interest in improving Overload!

Development Setup

Clone the repository and install it in editable mode with development dependencies:

git clone https://github.com/dprakash2101/overload
cd overload
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

The project uses pytest for unit testing. Before submitting a Pull Request, ensure the entire test suite passes.

pytest tests/

To stop on the first failure:

pytest tests/ -x

Development Principles

• First Principles: Understand the underlying problem before coding. Don't copy patterns blindly.
• PEP 8: Follow standard Python PEP 8 formatting guidelines.
• Async Only: All I/O-bound operations (HTTP requests, file I/O during tests) MUST use async/await. Never block the event loop.
• Type Hints: All function signatures must be fully type-hinted. Add from __future__ import annotations at the top of new files.
• Dataclasses: Use standard library dataclasses for internal state management (not Pydantic, which is only used at the FastAPI layer).
• Logging: Do not use print() for debugging. Use Python's logging module. Ensure output is clean by default and verbose when --debug is passed.

Submitting Changes

1. Create a branch from main (e.g., git checkout -b feature/new-load-pattern).
2. Implement your changes. Keep PRs focused on a single feature or bugfix.
3. Add unit tests to cover your new logic.
4. Ensure all tests pass.
5. Write a clear commit message and open a Pull Request against `main`.