# Contributing to depwhy

Thank you for your interest in contributing. This guide covers everything you need
to get a working development environment and submit a pull request.

## Development Setup

You need [uv](https://github.com/astral-sh/uv) installed. Then:

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

This installs all runtime and development dependencies into an isolated virtual
environment managed by `uv`.

## 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 (hits real PyPI — requires network)
uv run pytest --integration

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

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

## Code Quality

All of the following must pass before committing:

```bash
# Lint
uv run ruff check src/ tests/

# Format (rewrites files in place)
uv run ruff format src/ tests/

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

Additional rules enforced in review:

- All public functions and classes must have docstrings.
- All function signatures must have complete type annotations.
- No `# type: ignore` without an explanation comment on the same line.
- No `print()` in library code — use `logging` or `rich.console.Console` (CLI only).
- Maximum line length: 100 characters.

## Commit Message Format

This project uses [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(scope): short description
fix(scope): short description
test(scope): short description
docs(scope): short description
refactor(scope): short description
chore(scope): short description
```

Examples:

```
feat(cli): add --json output flag
fix(detector): handle circular dependencies without infinite loop
test(fixtures): add ml_stack_conflict fixture
docs(readme): update library API example
```

The scope should match the component being changed: `cli`, `fetcher`, `parser`,
`graph`, `detector`, `ranker`, `explainer`.

## Pull Request Process

1. Create a feature branch from `main`:
   ```bash
   git checkout -b feat/your-feature
   ```

2. Make your changes. Run the full quality suite before pushing:
   ```bash
   uv run ruff check src/ tests/ && uv run ruff format src/ tests/ && uv run pyright src/ && uv run pytest
   ```

3. Push your branch and open a pull request against `main` on GitHub.

4. The CI workflow runs automatically. All checks must pass before a PR can be merged.

5. Address review feedback, then request a re-review.

## Reporting Issues

Open an issue at https://github.com/terrymccann/depwhy/issues. Include:

- Your Python version (`python --version`)
- Your `depwhy` version (`depwhy --version`)
- The requirements file or list of packages that triggered the problem
- The full output, including any error messages
