Contributing

Development Setup

Prerequisites: Python 3.10+, uv

bash
git clone https://github.com/terrymccann/depwhy
cd depwhy
uv sync --extra dev

Running Tests

bash
# All unit tests (no network access)
uv run pytest

# Run a single test file
uv run pytest tests/test_detector.py -v

# Integration tests (requires network)
uv run pytest --integration

# Coverage report (85% minimum enforced)
uv run pytest --cov=depwhy --cov-report=html

Tests use respx to mock HTTP calls, so the standard suite runs entirely offline.

Code Quality

All checks must pass before committing:

bash
# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type checking (strict mode)
uv run pyright src/

Rules enforced:

  • All public functions/classes must have docstrings
  • Complete type annotations on all function signatures
  • No # type: ignore without explanation
  • No print() in library code (use logging or Rich)
  • Max line length: 100 characters

Commit Message Format

Uses Conventional Commits:

text
feat(scope): short description
fix(scope): short description
test(scope): short description
docs(scope): short description

Valid scopes: cli, fetcher, parser, graph, detector, ranker, explainer

Pull Request Process

  1. Create feature branch from main
  2. Make changes and run full quality suite
  3. Push and open PR against main
  4. CI runs automatically — all checks must pass
  5. Address review feedback

Reporting Issues

Open an issue on GitHub with:

  • Python version
  • depwhy version
  • Requirements file content
  • Full terminal output