Contributing to Overdue#

Thanks for wanting to help out! Whether you're fixing a typo, adding a feature, or reporting a bug, every contribution makes the library a better place.

Getting Set Up#

With Docker#

The fastest way to get a working environment:

git clone https://github.com/onlydole/overdue.git
cd overdue
docker compose up --build

The app will be running at http://localhost:8000.

Without Docker#

git clone https://github.com/onlydole/overdue.git
cd overdue

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

# Start the dev server
uvicorn src.main:app --reload

Running Tests#

pytest

To run with coverage:

pytest --cov=src

Code Style#

We use Ruff for linting and formatting. Run both before submitting a PR:

ruff check src/ tests/
ruff format src/ tests/

Commit Conventions#

We follow Conventional Commits. Scope is optional but encouraged:

feat(game): add Marathon Reader badge
fix(catalog): handle empty search queries
docs: update quickstart guide
test(auth): add token refresh tests
chore: bump dependencies

Making a Pull Request#

1. Fork the repo and create a branch from main
2. Make your changes -- keep commits focused and atomic
3. Run pytest and ruff check to make sure everything's clean
4. Push your branch and open a PR
5. Describe what you changed and why in the PR body

That's it. We'll review and get back to you.

Reporting Issues#

Found a bug or have an idea? Open an issue. Include:

• What you expected to happen
• What actually happened
• Steps to reproduce (if applicable)

Architecture#

If you're diving into the code, docs/architecture/overview.md gives you the lay of the land.

License#

By contributing, you agree that your contributions will be licensed under the MIT License.