# Contributing

Thanks for considering a contribution.

## Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
```

Copy env template:

```bash
cp .env.example .env
```

Then set real values in `.env` and run:

```bash
streamlit run app.py
```

## Development guidelines

- Keep architecture boundaries clear:
  - `clients/` for external integrations
  - `domain/` for normalization/business logic
  - `services/` for app services/indexing
  - `ui/` for Streamlit rendering
- Avoid introducing optional fallback paths unless required.
- Prefer small, focused functions and explicit session-state keys.
- Preserve safe SSH behavior and path quoting.

## Validation

Before opening a merge request, run:

```bash
PYTHONPATH=src python -m py_compile app.py src/media_library_viewer/*.py src/media_library_viewer/clients/*.py src/media_library_viewer/domain/*.py src/media_library_viewer/services/*.py src/media_library_viewer/ui/*.py
```

## Security / secrets

Never commit:

- `.env`
- `.streamlit/secrets.toml`
- private keys or API tokens

Use `.env.example` for documented placeholders only.

## Pull requests

Please include:

- what changed
- why it changed
- how it was tested

If behavior/requirements changed, also update `docs/REQUIREMENTS.md`.